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END USER LICENSE AGREEMENT BETWEEN THE “LICENSEE” AND SN SYSTEMS LTD “LICENSOR” 


LICENSE: SN Systems Ltd (SN Systems) hereby grant the Licensee a non-transferable, non-exclusive right to use the 
Licensor’s software product Tools on any single computer, provided that the Software is in use on only one computer at a 
time in return for the license fee. 

USE OE THE SYSTEM You may use the Software and associated User Documentation on any single computer fitted 
with Cartridge Hardware. You may also copy the Software for archival purposes, provided that any copy contains all the 
proprietary notices for the original Software. 

You may not: 

Permit other individuals to use the Software except under the terms listed above; 

Modify, translate, reverse engineer, decompile, disassemble (except to the extent applicable laws specifically prohibit such 
restriction) or create derivative works based on the Software; 

Copy the Software (except for backup purposes); 

Rent, lease, transfer or otherwise transfer rights to the Software; 

Remove any proprietary notices or labels on the Software 

TITLE: Title, ownership rights and intellectual property rights in and to the software shall remain in SN Systems Ltd. 

COPYRIGHT: The Software is owned by the Licensor. The Licensee may not copy the manual (s) or any other written 
materials accompanying the Software. 

LIMITED WARRANTY: The Licensor warrants that the Software will perform substantially in accordance with the 
accompanying manual (s) for a period of 30 days from the date of receipt PROVIDED that the failure of the Software has noi 
resulted from accident, abuse or misapplication. 

CUSTOMER REMEDIES The Licensor’s entire liability and the Licensee’s exclusive remedy shall at the Licensor’s 
option, either be: 

(1) return of the license fee paid or 

(2) repair or replacement of the Software that does not meet the Licensor’s Limited Warranty outlined above. 

DISCLAIMER OE WARRANTY: THE SOETWARE, ACCOMPANYING MANUAL (S) AND ANY SUPPORT 
PROM SN SYSTEMS ARE PROVIDED “AS IS” AND WITHOUT ANY OTHER EXPRESSED OR IMPLIED 
WARRANTY, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OP MERCHANTABILITY 
AND PITNESS POR A PARTICULAR PURPOSE. IN NO EVENT WILL SN SYSTEMS BE LIABLE POR ANY 
DAMAGES, INCLUDING LOST PROPITS, LOST SAVINGS OR OTHER INCIDENTAL OR CONSEQUENTIAL 
DAMAGES, EVEN IP SN SYSTEMS IS ADVISED OP THE POSSIBILITY OP SUCH DAMAGES OR POR ANY 
CLAIM BY YOU OR ANY THIRD PARTY. THIS DISCLAIMER OP WARRANTY CONSTITUTES AN 
ESSENTIAL PART OP THE AGREEMENT. 

SN Systems’ liability under this Agreement whether in contract, tort (including negligence) or otherwise shall be limited to 
the Fee paid by the Licensee. 

TERMINATION: This license will terminate automatically if you fail to comply with the limitations described above or if 
after thirty (30) days written notice to SN Systems, you terminate it. On termination you must destroy all copies of the 
Software, in whole or in part, in any form and cease all use of the Software. 



Please note that as this software is constantly being updated, it is quite likely that this manual 
may contain some inaccurate or out-of-date references and some features of newly updated 
software may not be fully covered. 

For this reason, if you experience any difficulties with this documentation, updates are 
available for download via the SN Systems BBS. 

We recommend that you make regular use of this service and quickly take advantage of any 
new features added to the software, report or download ‘bug’ reports, gain answers to 
questions that may be causing you difficulty and keep up-to-date on news concerning the 
development industry. 

If you experience any difficulties, please do not hesitate to contact our Technical Support at 
SN Systems: 

Tel: +44 (0)117 929 9733 

Fax: +44 (0)117 929 9251 


This device complies with part 15 of FCC Rules. Operation is subject to the following two 
conditions: 

1) This device may not cause harmful interference 

2) This device must accept any interference that may be received, including interference that 
may cause undesired operation. 


© 1996, 1997 SN Systems Software Ltd. All rights reserved. 
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Introduction 


This system is a fast PC based cross development systefor producing and testing 
mixed C and/or assembler programs for the Nintendo 64 games console. 


This version of the system features: 

• High performance SCSI interface card for host PC 

• Compact Nintendo 64 adapter cartridge this includes 32 Mbytes of cartridge 
emulation RAM 

• All the software you need:- 

• A RISC R4300 assemblecompatible with standard C compilers including the 
popular Freeware Gnu-C. 

• Fast R4300 assembler with numerous directives. 

• High Speed Linkeiand Librarian, with extensive link-time options. 

• A powerful Source Level Debugger whichllows the programmer to step, 
trace and set breakpoints directly in the source code. 


Additional hardware required 

• Host 386/486/Pentium PC with hard disk driv^t least 16 Megabytes of 
memory and 1 free 16 bit ISA slot. 

• Nintendo 64 and a valid games cartridge. 

Additional software required 

• Windows 95 with Microsoft Internet Explorer. 
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About This System 


• This systemhas been developed b}SN Systems Ltd who have many years 
experience of development software and developers' needs. It represents the next 
generation of development systems, backed up by a commitment to continual 
enhancement, development and technical support. 

• The systemincludes two industry-standard Assemblers, a Linker, a Debugger and 
a C and C-i-i- compiler The Assemblers are extremely fast, and fully compatible 
with other popular development systems. 

• It offers Source Level Debugging. This allows you to step, trace, set breakpoints, 
etc. in your original C or Assembler source code. The system automatically and 
invisibly, handles multiple text files. 

• It provides a high-speed genuine SCSI parallel liilletween the Host PC and 
target system, with a data transfer rate of over 1 Megabytes per second. The 
system supports up to 7 connected target devices 
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The System for Nintendo 64 


The target interfaceis a compact cartridgethat plugs into the cartridge portaf the 
Nintendo 64. 

Adapter firmwareprovides diagnostics and self-test facilities. Also included are 
assorted functions for useful run-time control of the development environment, as 
well as extensive fileserver facilitias'hich allow the target to manipulate files on the 
host PC. 
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Issue Information 


Compatible development systemsare available for a variety of other platforms: 

• Sony PlayStation 

• SEGA Saturn 

• SEGA32X 

• SEGA MegaDrive/Genesis 

• SEGA Mega-CD 

• Nintendo Super NES 

• Commodore Amiga 1200 and 600 

• Williams Phoenix Arcade Board 

Nintendo Development Software 

The software for Nintendo 64 comes on fouri^“ HD disks. Disk 1 and 2 contain all 
the System software, including the R4300 Assembler, Debugger etc. Disk 3 and 4 
contain an archive of the ‘Ereeware’ GNU C compiler. 


Note: A number of Nintendo 64 specific Eibraries are provided by Nintendo. 
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CHAPTER 1 

Installation 


The development system consists of the following physical components: 

• PC Board 

• Target Interface 

• SCSI Connecting Cable 

• Mains Connecting Cable 

• Software 

• Universal Power Supply - lEC Socket, rating I00-250v a.c., 47-63 Hz 


Warning: For the Nintendo 64 Development Cartridge you mudnly use the 

supplied 5V regulated power pack. Use of any other type will cause 
serious damage to the Unit. 


Installation is, therefore, a relatively straightforward procedure, and is described in 
this chapter under the following headings: 

• Installation The Hardware 

• Installing The PC Interface 

• Installing The PC Software 

• Installing The GNU C Software 

• Checking The Installation And First Time Use Of The System 

• Requirements For Debugging Cartridge Software 

• Additional Notes 

• Elfconv - Uibrary Converter Program 
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Installing The Hardware 


1. Check the configuration of the SCSI Cardnd install in the host PC; see later in 
this chapter for full installation details. 


Note: Ensure that you record thelO Address and IRQ value as these will be 
required when you install the software. 


2. Plug a standard Nintendo 64 game cartridge. g. Mario64 or Pilotwings64) into 
the through connector at the back of the unit, so that the cartridge is front face up 
when the interfaceis inserted in the Nintendo 64. The cartridge is required to 
provide the security chipand the 4k boot header block You should also be able 

to make use of any additional hardwaren the cartridge, e.g. game save memory. 

3. Plug the interface into the Nintendo 64; the LEDshould be towards the front. 


Note: Ensure that the Nintendo 64 is switcheMf at this point. 


4. Connect the SCSI cable to the PC. 
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5. Plug the power supplyinto the side of the interface. The power LED (the top 
one) should come on and the lower LED should flash. Check the hardware if the 
lower LED is not flashing. 


Note: At this point the Nintendo 64 shouldtill be switched off. 
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Installing the PC Interface 

The PC Interface boardshould be fitted in to an empty 16 bit sldln the host PC. The 
host must be an IBM PC-AT or compatible, running under MSDOS 3oI better. 

Prior to fitting, the 3 banks of dip switcheshould be checked and configured as 
required. It is likely, however, that the factory setting will suffice. They are described 
below. 



50 Pin High 
Density SCSI 
Connector 
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DIP SWITCHES 

The PC card is configured by altering the three dip switdhanks on the card. These 
switches alter: 

DMA 

IRQ 

SCSI Termination Power 
lO Address 

SCSI ID for the card (normally on ID 7) 


FUNCTION 

DEFAULT 

DMA 7 

On, On 

DMA 6 

Off, Off 

DMA 5 

Off, Off 

IRQ 15 

On 

IRQ 12 

Off 

IRQ II 

Off 

IRQ 10 

Off 

IRQ 7 

Off 

IRQ 5 

Off 

Not Used 

Off, Off 

SCSI Termination Power 

On 

10 Address - A3 - A8 

Off, On, On, On, On, Off 

Card SCSI ID 

On, On, On 


DMA DMA or Direct Memory Access, is a mechanism for the fast and efficient transfer of 

data (in either direction) between the SCSI card and the PC’s memory. 

This transference occurs via DMA channeB, 6 or 7. 

Only one channel can be used per card; if more than one card is in use a different 
DMA channel must be used for each one. 


Note: Data transfermay be interrupted if the same channel is used for more than one 
card. 


A channel is selected by switching the pair of adjacent dip switchesQn and the 
remaining pairs toOff. 


© SN Systems Ltd 





Page 1-6 


Installation 


Nintendo 64 


The default setting is7; this is achieved as follows: 


DMA 7 - On, On 
DMA 6 - Off, Off 
DMA 5 - Off, Off 


Note: In each pair, both switches must be set to the same value. 


Note: If all DMA dip switches are set to Off, the transfer of data will be slower 
because this process will instead be carried out by the PC Processor 


IRQ An Interrupt Request (IRQ) number can be assigned to each attached device so that 

it can quickly interrupt the PC Processor with a request. 

When the PC receives an Interrupt Request it goes to a look-up table and ascertains 
the purpose of the sub-routine attached to the IRQ number; it then processes this 
sub-routine as soon as possible. 

The SCSI Card offers the following IRQ numbers. 

15, 12, 11, 10, 7, 5 

Select the required number from this list by switching the adjacent dip switchOn. 


Note: You cannot use an IRQ number which is being used by another device. The 
following procedures will list those currently in use: 


1. From the Start menu select th^ettings option. 

2. Select Control Panel. 

3. Double-click the Systems icon. 

4. Select the Device Manager tab. 

5. Select the Properties button. 

6. Select the Interruptrequest (IRQ) button. 

The IRQ numbers currently in use will be displayed. 


Note: The default IRQ setting for the SCSI Card ii5. 


Note: It is possible to disable the IRQ number by removing all the jumpers but this 
may result in an impaired performance. 


Note: The SCSI card setting must match that which will be later specified for the 
software. 
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Note: If you use a PCI Mother Board it may be necessary to make the IRQ available 
to the ISA Device in thebios . See the Mother Board documentation for 
further information. 


SCSI Termination Power 

The SCSI Termination Poweiswitch determines whether SCSI termination is 
supplied on the card. Correctly applied termination minimises electrical interference 
without it the communication between the devices would become erratic. 

The SCSI devices are connected in a chain structure. Termination is only required by 
the devices at each end of the chain. 

The default setting for this configuration i0n. 

In normal operation this shouldiot be changed. 


lO Address The 10 Addressprovides a channel of communication between the SCSI card and the 
PC. 

You must first set the card to a hardware 10 Address and then set the software to 
access it at that address. 


Note: If the hardware address does not match the software setting, a message will 
indicate that the card is not found at that address. 


The card offers a very large range of 10 addresses fro^Oie to 3f8ie in increments 
of 8. The address is changed by altering the 6 dip switches labeled A3 to A8. 

A8 is the most significant bit, anA3 is the least. 

An address line is selected by switching it t(£)ff. 

The default setting is308; this is set as follows: 

IQ Address A3 - A8 - Off, On, On, On, On, Off 
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Some examples are shown in the following table: 



A8 

A7 

A6 

A5 

A4 

A3 

240 

On 

On 

Off 

On 

On 

On 

2A0 

On 

Off 

On 

Off 

On 

On 

300 

Off 

On 

On 

On 

On 

On 

308 

Off 

On 

On 

On 

On 

Off 

310 

Off 

On 

On 

On 

Off 

On 

318 

Off 

On 

On 

On 

Off 

Off 

380 

Off 

Off 

On 

On 

On 

On 

388 

Off 

Off 

On 

On 

On 

Off 

390 

Off 

Off 

On 

On 

Off 

On 

3E0 

Off 

Off 

Off 

Off 

On 

On 


Note: You must not choose an address which ithe same as or within the range of 

addresses occupied by another card as this would cause unpredictable results. 
Use the following procedures to list those currently in use: 


1. From the Start menu select th^ettings option. 

2. Select Control Panel. 

3. Double-click the Systems icon. 

4. Select the Device Manager tab. 

5. Select the Properties button. 

6. Select the InputCutput (I/O) button. 

The currently used addresses will be displayed. 


SCSI ID Each attached device has its owiSCSI ID which uniquely identifies it on the SCSI 
bus. 

The last three switches are used to alter th^CSI ID. 

The default setting is7; this is set as follows: 


Card SCSI ID - On, On, On 


Note: You are advised not to change this setting (or re-use it for another card) as it 
has been pre-allocated in order to minimise any conflict with other internal 
boards. Any SCSI ID duplicatioBcould result in unpredictable results. 
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Installing the PC Software 


The installation discs contain programs to perform the following functions: 

• Assembling 

• Linking 

• Debugging 

• Other Windows and miscellaneous tasks 


To install the Development Tools: 


Note: The tools must be installedbefore the GNU C Compiler. 


1. Insert the first development tools disc in the ‘A’ drive. 

2. Double-click the ‘A’ drive icon on your desktop and select the .exe file. 


3. Select 


Yes 


to view the installation help file o- 


No 


to 


continue with the installation. 


4. Select to confirm the Licence Agreement o- 

the installation. 


Cancel 


to abort 


5. The Select Components To Install dialog will be displayed. A tick will be shown 
alongside the Tools and the Debugger. Selec to install both items. 


6. From the Select Destination Directory Dialog, sele( to confirm that 

you wish to place the Tools in the displayed directory or browse and select an 
alternative from the directory listing if required. 


7. 


To automatically set-up PSYQ_PATH in autoexec.bat, seledii 
the Edit Autoexec dialog. 


at 


8. From the Select Destination Directory Dialog, sele( to confirm that 

you wish to place the Debugger in the displayed directory or browse and select an 
alternative from the directory listing if required. 


Note: At this point you willalso be required to specify a directory (or accept the 
default) for the GNU C Compiler. 


9. 


Insert the second tools disc and selec 


OK 


10. Select 


Yes 


to insert a short-cut for the Debugger on the Start menu. 
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11. Set the required values for the SCSI card as follows: 

Enter a 3 or 4-digit hexadecimal number to thPort Address and specify anIRQ 
value by clicking on the down arrow and selecting as appropriate. 


Note: The values specified here must match those already specified on the 
hardware. 


12 . 

13. 


Select 


Yes 


No 


or ■ 


at the Verify Values dialog. 


Select to restart your PC to complete the installation. 

The Tools and Debugger are now installed. 


© SN Systems Ltd 










Nintendo 64 


Installation 


Page 1-11 


Installing the GNU ‘C’ Software 


After you have installed the toolsn their own directory on your hard dislg^'ou are 
ready to install the popular GNU ‘C’ N64 Compiler 

The disk contains all of the files provided by GNU for the N64 ‘C’ Compiler. For 
Nintendo 64 software development you may require components that can only be 
obtained directly from Nintendo. These include a number of useful Libraries and their 
C Header files which are specific to the Nintendo 64 environment. If you do not 
already have this software, you should contact Nintendo directly. 


To install the GNU C Compiler: 


1. Insert the first GNU C Compiler disc to the ‘A’ drive. 

2. Double-click the ‘A’ drive icon on your desktop. 

3. Select the .exe file. 

ni^ Odno0l 

4. Select if you agree to the Licence Agreement o to exit 

the installation. 

5. The Select Directory For GNU C Compiler dialog will be displayed. Select 

to confirm the displayed directory or browse and select an alternative 
directory in which to place the GNU C Compiler. 

6. Insert the second disc and selec 
The installation is now complete. 


Note: The library from Nintendo will have to be converted froelf format to the 
System’s format See theelfconv documentation below for further details 
about this process. 
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Checking The Installation and First-Time Use Of The System 


Checking the Installation: 


Note: Before proceeding with your installation check read the README file for any 
last minute changes or final release notes. This will be called 
README.HTM or README. RTE and will be found in tlpsyq-win 
directory. 


1. At this point the Nintendo 64 should be switched off and the Target Adapter and 
game cartridge should be connected to it. The power should be on for the 
Adapter and the bottom EED should be flashin^owly, indicating that thebios 
has not yet been loaded. 


Note: If the EED is flashing quickly this indicates that the Nintendo 64 is 
switched on and nobios is loaded. This is an error whichnust be rectified by 
switching the Nintendo 64)ff. 


2. Run the Eile Server by selecting the Debugger Eile Server from the Start menu. 

3. This will attempt to connect to the Nintendo 64 console. If the connection is 
successful the Eile Server will download the bios; the bottom EED will go out 
and the following text will be output from the Eile Server: 

Psy-Q File and Message Server, Copyright 1996, 1997, SN Systems Ltd 
Version 2.0 (January 1997) 

Release 10, Patch Level 3 

Target Found: Bus ID = 0, SCSI ID = 0 

New Downloader - Reading profile information... 

Profile read for Nintendo 64 (no hios) 

OK 

Rebooting the Nintendo 64 (no hios)... 

Getting the target’s ID... 

ID is N64-NO-BIOS PLEASE LOAD 

hiosl... 

sleep .5 sec... 

hios2... 

sleep .5 sec... 

New Downloader - Reading profile information... 

Profile read for Nintendo 64 
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If this has occurred communication will have been established between the PC 
and the Nintendo 64. 

4. Now you are ready to download a test cartridge image into the cartridge RAM. 
Proceed as follows: 

5. From the File Server select th^ools menu. 

6. Select the Uploader option. 

7. Click the Download radio button and change thOownload Addressto 

OxBOOOOOOO . 

8. ClickBrowse and select the filetest .bin from thepsyq-win\examples\n64 
directory. 

9. Click OK. 

The downloaded image is now in the cartridge RAM. 

10. Switch on the Nintendo 64. The system will boot the image and stop at a 
breakpoint at the start of the program. 

11. Run the Debugger from the Start menu. 

12. You are now ready to begin debugging. 

Note: To convert the Nintendo 64 object files use thElfconv converter program; 
this is described below. 
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Requirements for Debugging Cartridge Software 


In order to be able to debug your own program you must link in the debug stub code 
This consists of two object modulesccupying approximately 8k of ram. These are 
PSYQ.OBJ andPSYQDBG.OBJ. They contain only one entry point 
' init_debug' which must be called at the start of the program. The entry point 
will hook the debug vectomt $80000180 . The programs will pass any 
interrupts/exceptions that they do not know how to handle to the previous address in 
this vector; therefore 'ini t_debug' should not be called until this vector has 
been initialised, i.e. contains a valid address. The debug stub will not function until 
'init_debug' has been called; therefore any exceptions occurring before this 
will not be handled. 

Further details can be found in the test program’s Sourcaend Linker Control Files 

If the MIPS chip in the Nintendo 64 stops communicating with the microcontrolihar 
the cartridge for any reason (e.g. the power is off or the program crashes badly), then 
the microcontroller will inform the Debugger (or any other program running on the 
PC and trying to communicate with the target) that the Nintendo is not responding 
and the error message Target Unit Is Busy” will be displayed. If the target 
recovers or you reset it, the message will go away and the Debugger will continue to 
run. 

The interface uses a hardware interrupto force the MIPS chip in the Nintendo 64 to 
enter the debug stub. This means that it will not normally be necessary to add ‘poll 
calls’ to your program unless you need to break in at points where interrupts are 
disabled. 
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Additional Notes 


• The system has 32 Mbytes of ram fitted for cartridge emulation but the top 128k 
(OxBlFEOOOO - OxBlFFFFFF) is reserved for debug purposes. 


Note: Do not load anything into this area or it will be erased. 


• After you produce the cartridge image and before you load the games program 
into the Nintendo system, the program' set csum. exe' will set the load/entry 
point of your program and the required checksum valueS'he minimum size for 
a cartridge is lMbyte+4Kbytes; if your code is smaller than this it will be padded 
to this length. The first 4k of the game images a boot block. Most of the data 
in this block is shadowed through at Nintendo 64 boot up from the data in the 
cartridge you have plugged into the interfaceSet csum. exe will set any other 
required values so all you need do is have a 4k block of Os at the start of your 
cartridge image. 


Note: See the test programin psyq-win\examples\n64for an example of this. 

• The debug stub disables all interrupts while it is executing. 

• Although the Assemblers and Linker support the use of the instructions for 
manipulating 64 bit dat^e.g. Id, sd etc), they still only contain a 32 bit 
expression evaluatorso 64 bit constants cannot be used. 

• The debug stub does not support the use of memory mapping the region 
0x00000000 - OxVFFFFFFF or OxCOOOOOOO - OxFFFFFFFF via 
the TLB. Only 00s will be seen in these areas at the moment. 
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ELFCONV - Library Converter Program 


The Nintendo 64 librariesupplied by Nintendo contain object fildn a file format 
known as ELE These files must be converted to SN System’s object file format if 
the libraries are to be used with SN development softwar^lfconv is a utility 
program which performs this conversion. 


► 


To convert a library 


1. Three programs are required; one for each of the three stages of conversion: 

• A library toolwhich understands EEE libraries this will extract the object 
files from an EEE format library, creating one or more files with.® 
extension. 

• Elfconv, this can convert all. o files found in the current directory, a single 
file or all files matching a given pattern. The output from elfconv is one or 
more files with a. ob j extension. 

• SN System’s PSYEIB librarian prograpithis will combine one or more 

. ob j files into an SN format library, suitable for linking with PSYEINK 

2. The Nintendo 64 libraries are supplied for the SGI works tatipithe first program 
should therefore be the SGI’s standard ‘ar’ library tool. On the SGI workstation, 
locate the library file(s) you wish to convert and type the following to extract all 
the object files from each library: 

ar X libraryname 

This will create one or more .o files in the current directory, reflecting the 
contents of that library. 

3. Copy these files to your PC. 

4. As Elfconv’ s operation on each file is automatic, you only need to tell it which 
files to convert via one of the following methods:. 

elf conw input output 
elf con\ input 
elfconv /a 

Eor the first method elfconv will search for the file with nam^ut and convert it 
to a file namedoutput 
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If you specify only an input file, elfconv will convert the relevant file and create 
an output file with the same name but witbb j suffixed to its extension. 

For the third method all files with o extensions will be converted as per the 
second method. 

Thus: 

elfconv filel.o filel.obj Converts filel . o into f ilel . ob j 
elfconv filel.o Converts filel . o into filel . obj 

elfconv /a Converts all . o files in the current 

directory into . obj files 

Elfconv will report the following kinds of errors 

A missing input file 

An input file which is not recognisable as an ELF object file. 

Inability to create the output filc(usually if there is no disk space). 

Fatal and non-fatal errorsduring conversion of the file; these start with ! ! " for 
fatal and ">>" for non-fatal errors. 

Note: You should not receive any fatal or non-fatal errors if elfconv is working 
correctly and you are converting a genuine N64 library file. If you do 
receive any errors, contact SN Systems for support. 

5. After you have converted your object files, use PSYLIB to create an SN format 
library. See the PSYLIB chapter for further details. 
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CHAPTER 2 

The ASMN64 Assembler 


The ASMN64 Assembler can assemble source code at over 1 million lines per 
minute. Executable image or binary object code can be downloaded by the Assembler 
itself, to run in the target machine immediately, or later, by tlKJN utility. 

This chapter discusses how to run an assembly session, under the following headings: 

• Assembler Command Line 

• Assembler and Target Errors 


© SN Systems Ltd 





Page 2-2 


ASMN64 Assembler 


Nintendo 64 


Assembler Command Line 


During the normal development cycleVSMN64 may be: 

• run in stand alone mode 

• launched from an editing environment such as Brief - see later in thhsapter 

• invoked as part of theMake utility - see The Psymake Utility chapter. 

When the Nintendo 64 Assembler is run independently, the command line takes the 
following form: 


Syntax ASMN64 /switchlistsource,object,symbols,listings,tempdata 
or 

ASMN64 @commandfile 

If the first character on the command line is a@ sign, the string following it signifies 
a command filecontaining a list of Assembler commands. 

Switches The assembly is controlled by inclusion of a set of switches, each preceded by a 

“forward slash (/)”. The “/o” switch introduces a string of assembler options; these 
can also be defined in the source code, using a0PT directive. Assembler options 
are described in detail in chapter 9, the available switches are listed below: 


/c 


Produce list of code in unsuccessful conditions 

/d 


Set Debug mode - if the object code is serilto the target 
machine, do not start it. 

/e 

n=x 

Assigns the valuer to the symbols. 

/g 


Non-global symbols will be output directly to the linker 
object file. 
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Source 

Object 

Symbols 

Listings 

Tempdata 


/j pathname 

/k 

/I 

/m 


Nominate a search path fodNCLUDE files. 

Permits the inclusion of pre-defined foreign conditionals, 
such asIFND - see also MACROS, chapter 5. 

Output a file for the Psylink Linker. 

Expand all macros encountered. 


/o options Specify Assembler options - see chapter 9 for 

a full description of the available options. 


/p 


Output pure binary object code, instead of an executable 
image in cpe format - see also RUN. EXE chapter 2. 


/ps 


Output ASCII representation of binary file in Motorola 
s -record format 


/w Output EQUATE statements to the Psylink file, 

/z Output line numbers to the Psylink file. 


/zd 


Generate source level Debug information. 


The file containing the source code; if an extensidn not specified, the default is n64 
. If this parameter is omitted, the Assembler outpulhelp in the form of a list of 
switches. 

The destination file to which object code is written. 

The file to which symbol information is written, for use by the Debugger. 

The file to contain listings generated by assembly. 

This parameter nominates a file to be placed on tlfiAM disk for faster access. If 
the name is omitted, the default iasm.tmp; note that the temporary file is always 
deleted after assembly is complete. 
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Remarks 


Examples 


• If any of the above parameters are omitted, the dividing comma must still be 
included on the command line, unless it follows the last parameter. 

• The Assembler run may be prematurely terminated by any of the following 
methods: 

Pressing Control-C. 

Pressing Control-Break (recognised more quickly because it does not require 

a DOS operation to spot it). 

Pressing Esc. 

• The Assembler checks for an environment variabialled ASMN64. This can 
contain default options, switches and file specifications, (in the form of a 
command line), including terminating commas for unspecified parameters. 
Defaults can be overridden in the runtime command line. 


asmn64 / zd / o ae+,w- scode, tO : , scode . sym 

This command will initiate the assembly of the R3400 source code contained in a file 
calledscode. n64, with the following active options: 

• source level debug informatiorto be generated 

• automatic alignmentenahled 

• warning messages to be suppressed 

• the xesvXtantobject codeto be transferred directly to thetarget machine, SCSI 
device 0 

• symbol informationto be output to a file calledscode.sym 

• assembly listingto be suppressed 

ASMN64 0game.pcf 

will recognise the preceding @ sign and take its command line from a command file 
called GAME. PCF . 
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Assembly Errors 


During the assembly process, errors may be generated as follows: 

By the assembler itself, as it encounters error conditions in the source code. 


Remarks 


Appendix A gives a full list of Assembler error messages, 
plus 

Abort, Retry or Bus Reset 
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CHAPTER 3 

Syntax of Assembler Statements 


In order to control the running of an Assembler, source code traditionally contains a 
number of additional statements and functions. These allow the programmer to direct 
the flow and operation of the Assembler as each section of code is analysed and 
translated into a machine-readable format. Normally, the format of Assembler 
statements will mirror the format of the host language, and ASMN64 follows this 
convention. 

This chapter discusses the presentation and syntax of Assembler statements, as 
follows: 

• Format of Statements 

• Format of Names and Labels 

• Constants 

• Functions 

• Operators 

• RADIX 

• ALIAS and DISABLE 
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Format of Statements 

Assembler statements are formatted as follows: 

Name or Label Directive Operand 
The following syntactical rules apply: 

• Individual fields are delimited by spaces or tabs. 

• Overlong lines can be split by adding an ampersand J^he next line is then 
taken as a continuation 

• Lines with an equals (=) sign as the first character are considered to be the case 
options of a CASE statement - see Flow Control, chapter 4. 

• Comment Lines 

• comments normally follow the operand, and start with a semicoloi).(; 

• lines which consist of space or tab characters are treated as comments. 

• a complete line containing characters other than space or tabs is treated as 
a comment, if it starts with a semicolon or asterisk. 
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Format of Names and Labels 


Names and Labels consist of standard alpha-numeric symbols, including upper-case 
letters, lower-case letters and numeric digits: 

A to Z, a to z, 0 to 9 

In addition, the following characters can occur: 

Colon (:) Can be used at the end of a name or label when defined, but not 
when referenced. 

Question Mark (?), Underscore O, Dot (.) 

These three characters are often used to improve the overall 
readability 

AT sign @ Indicates the start of a local label - see chapte?. Note 

that, by using the Assembler optioi/iln, the local label symbol can 
be changed to a character other than @ . 

The following usage rules apply throughout: 

• Numeric digits and Question Marks must not be the first character of a name. 

• Labels normally start in column 1 . However, if they start elsewhere, there must be 
no characters preceding the name, except space or tab, and the last character 
must be a colon. 

• If a problem in interpretation is caused by the inclusion of a non- alphanumeric 
character in a Name or Label, that character can be replaced by a backslash, or 
the entire Name or Label surrounded by brackets. 
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Format of Constants 

The Assembler supports the following constant types: 

Character Constants 

A character string enclosed in quote marks is a character constant and is evaluated as 
its ASCII value. Character constants may contain up to 4 characters, to give a 32 bit 
value. Thus: 

"A" = 65 

"AB" = (65*256) + 66 

"ABC" =(65*65536) +(66*256) + 67 

"ABCD"= (65*16777216)+ (66*65536) + (67*256) + 68 

Integer Constants 

Integer constants are normally evaluated as decimal, the default base, unless one of 
the following is used: 

• The RADIX directive changes the base - see chapter 3. 

• If % , $ or Ox precede an individual integer, it signifies that the integer value 
will be evaluated as binary or hex: 

% - Indicates that the base is binary, e.g%1001 
$ - Indicates that the base is hex, e.g$45af 3921 
Ox - Indicates that the base is hex, e.g.0x45af3921 

Two possible characters are provided for base hex because optiont- (either / or 
+ on the command line oropt r+ in the source), will allow the$ prefixed 
versions ofregister names to be used but will disable the use of to prefix hex 
constants. The Ox prefix however, can still be used with this option, e.g: 

opt r- 

Iw aO, $14 (tO) ; or Iw aO, 0x14 (tO) 

; or Iw aO, 20 (tO) 

This operation takes the address in registetO, adds the 1 4 (hexadecimal) value 
to it and then takes the value at that address and puts it intaO. 

This code is equivalent to: 

opt r+ 

Iw $4, 0x14 ($8) ;or Iw $4, 20 ($8) 


= 65 
= 16706 
= 4276803 
= 1094861636 
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• If a character is preceded by a backslash and up arrow (K^he corresponding 
control character is substituted. 

• The AN Assembler option allows numbers to be defined as Intel and Zilog 
integers. That is, the number must start with a numeric character and end with 
one of: 

D for Decimal;H for Hexadecimal^ for Binary 
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Special Constants 

The following pre-defined constants are available in ASMN64. 

_year As a two digit number, e.g. 95 

_month 1 = January; 12 = December 
_day 1 = 1st day of month 

_weekday 0 = Sunday; 6 = Saturday 

_hours 00 - 23 

_minutes 00-59 

_seconds 00-59 

* Contains the current value of the Location Counter. 

@ Contains the actual PC value at which the current value will be 

stored - see below. 

narg Contains the number of parameters in the current macro argument - 

see chapter 5 for further details. 

rs Contains the current value of RS Counter - see chapter 4 for 

further details. 

_filename A pre-defined string containing the name of the primary file 
undergoing assembly. 

Remarks Time and Date Constants: 

Time and Date constants are set to the start of assembly; they are not updated during 
the assembly process. 

Example RunTime db\#_hours : \#_minutes : & 

\#_seconds" 

this expands to the fovmhh:mm:ss, as follows 

RunTime db "21:08:49" 

Note: This example uses the special macro parameter, \#, which is described in 
Chapter 5. 
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Location Counter constants: 

The current value of the program pointer can be used as a constant. To substitute the 
value of the location counter at the current position, an asterisk (*) is used: 

section Bss,g_bss 
Firstbss equ * 

Since * gives the address of the start of the line, 

org $100 

dw * ^ ^ * 

defines $100 three times. 

An @, when used on its own as a constant, substitutes the value of the location 
counter, pointing to an address at which the current value will be stored. 

org $100 

dw 0,0,0 

defines $100,$104,$108. 
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Assembler Functions 


ASMN64 offers many functions to ease the programmer's task. These are listed 
below; a more detailed explanation of their usage can be found later in this chapter. 
In addition, there are other specialised functions which are described in the following 
pages. 


Name 

Action 

def(a) 

Returns true if a has been defined 

ref(a) 

Returns true if a has been referenced 

type(a) 

Returns the data type ofa 

sqrt(a) 

Returns the square root ofa 

strlen(texO 

Returns the length of string in characters 

stxcY(vp{texta,textb) 

Returns true if strings match 

instr([5tort,] txa,txb) 

Locate substringa in stringb 

sect(a) 

Returns the base address of sectioia 

offset (a) 

Returns the offset into sectiona 

sectoff(a) 

Equivalent to offset 

group(a) 

Returns the base addres of group a 

groupoff(a) 

Returns the offset into groupa 
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Special Functions 


filesize( " filename ' ' ) 

Returns the length of a specified file, or -1 if it does not exist. 
groupsize(3Q Returns the current (not final) size of grou^. 

grouporg^O returns the ORG address of groupX or the group in whichX is defined iff is a 
symbol or section name. 

groupend(3Q Returns the end address of groups. 
sectend(X) Returns the end address of sectiorJf. 
sectsize(X) Returns the current (not final) size of sectiofiL. 


alignment(X) Gives the alignment of previously defined symlilfl This value depends upon the 
base alignment of the section in whiclf is defined, as follows: 

Word aligned - value in range 0 -3 
Halford aligned- value in range 0 -1 
Byte aligned - value alw^s 0 
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Assembler Operators 


The Assembler makes use of the following expression operators: 


Symbol 

Type 

Usage 

Action 

() 

Primary 

(a) 

Brackets of Parenthesis 

+ 

Unary 

+a 

a is positive 

- 

Unary 

-a 

a is negative (see Not^) 

= 

Binary 

a=b 

Assign or equateb to a 

+ 

Binary 

a+b 

Incrementa by b 

- 

Binary 

a-b 

Decrementa by b 

* 

Binary 

a*b 

Multiplya by b 

/ 

Binary 

a/b 

Divide a by b, giving the quotient 

% 

Binary 

a%b 

Divide a by b, giving the modulus 

« 

Binary 

a«b 

Shift a to the left, b times 

» 

Binary 

a»b 

Shift a to the right, b times 


Unary 

~a 

Logical compliment oiNOT a 

& 

Binary 

a&b 

a is logic allyANDed byb 

A 

Binary 

a'^b 

a is exclusiveljORed by b 

! 

Binary 

alb 

a is inclusiveljORed by b 

1 

Binary 

alb 

Acts the same as db 

<> 

Binary 

aob 

a is unequal tob 

< 

Binary 

a<b 

a is less thanb 

> 

Binary 

a>b 

a is greater thanb 

<= 

Binary 

a<=b 

a is less than or equalsb 

>= 

Binary 

a>=b 

a is greater than or equalsb 


Notel Since the Assembler will evaluate 32-bit expressions, the negation bit is 

Bit 31. Therefore, $FFFFFF and $FFFFFFF are positive hex numbers; $FFFFFFFF is 
a negative number 

Note^ If a comparison evaluates aSrue, the result is returned as-1; if it evaluates as 

false, the result is returned asO. 
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Hierarchy of Operators 

Expressions in the Assembler are evaluated using the following precedence rules: 

• Parentheses form the primary level of hierarchy and force precedence - their 
contents are performed first; 

• Without the aid of parentheses, operators are performed in the order dictated by 
the hierarchy table; 

• Operators with similar precedence are performed in the direction of their 
associativity - normally, from left to right, except unary operators. 


Operator 

Direction 

Description 

() 


Primary 

+ j -j ~ 


Unary 

«, » 


Shift 

&, 


Logical 

*, /, % 


Multiplicative 

+j - 


Additive 

>, <, <=, >= 


Relational 

=, <> 


Equality 
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RADIX 


Description The RADIX directive is used to change the default base of integer values appearing 
in source code (base 10), by over-riding the default with whatever base you specify. 


Syntax 

RADIX 

newbase 

Examples 

varl 

dw 17 


radix 

8 


var2 

dw 

17 

radix 

16 


var3 

dw 

17 

var4 

dw 

%1001 

Notes: 

varl is a value of 17 (decimal) 


var2 contains a value of 15 (decimal) 
var3 contains a value of 23 (decimal) 
var4 contains a value of 17 (decimal) 


Remarks 

• Acceptable values for the new base are in the range of 2 to 16. 

• Whatever the current default, the operand of thRADIX directive is evaluated to 
a decimal base. 


• The AN assembler option (see chapter 9) will not be put into effect if the default 
RADIX is greater than 10, since the signifierB andD are used as digits in 
hexadecimal notation. 
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ALIAS and DISABLE 


Description These directives allow the programmer to avoid a conflict between the reserved 
system names of constants and functions and the programmer's own symbols. 
Symbols can be renamed by thALIAS directive and the original names 
DISABLE'd, rendering them usable by the programmer. 

Syntax newname ALIAS name 

DISABLE name 


Remarks Symbolic names currently known to the Assembler may M^IASed and 

DISABLEd. However, these directives must not be used to disable Assembler 
directives. 


Examples _Offset 


alias offset 

disable offset 


_Offset dh 

offset dh 


_Offset (Lab) 
*-pointer 
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CHAPTER 4 

General Assembler Directives 


The Assembler provides a variety of functions and directives to control assembly of 
the source code and its layout in the target machine. 

This chapter documents the Assembler directives which allow the programmer to 
control the processes of assembly, grouped as follows: 


• Assignment Directives 

• Data Definition 

• Controlling Program Execution 

• Include Files 

• Controlling Assembly 

• Target-related Directives 
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Assignment Directive s 

The directives in this section are used to assign a value to a symbolic name. The value 
may be a constant, variable or string. 


• EQU 

• SET (and =) 

• EQUS 

• EQUR 

• Rsize 

• RSSET 

• RSRESET 
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EQU 


Description Assigns the result of the expression, as a constant value, to the preceding symbolic 
name. 


Syntax symbol name EQU expression 

See Also SET, EQUS 

Remarks 

• The Assembler allows the assigned expression to contain forward references. If 
an EQU cannot be evaluated as it is currently defined, the expression will be 
saved and substituted in any future references to the equate (see Note below). 

• It is possible to include an equate at assembly time, on the Assembler command 
line. This is useful for specifying major options of conditional assembly, such as 
test mode - see Assembler switches, chapter 2.. 

• Assigning a value to a symbol witEQU is absolute; an attempt at secondary 
assignment will produce an error. However, it is permissible to re-assign the 
current wdXuQ to an existing symbol; typically, this occurs when subsidiary code 
redefines constants already used by the master segment. 


Examples 

Length 

equ 

4 


Width 

equ 

8 


Depth 

equ 

12 


Volume 

equ 

Lenqth*Width*Depth 


DmaHigh 

equ 

$ffff8609 


DmaMid 

equ 

DmaHiqh+2 

Note 

List 

equ 

Lastentry-Firstentry 


if Firstentry,Lastentry not yet defined, then: 
dw List+2 

will be treated as 

dw (Lastentry-Firstentry) +2 

the equated expression is implicitly bracketed. 
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SET 


Description Assigns the result of the expression, as sariable, to the preceding symbolic name. 


Syntax 


symbol name SET expression 
symbol name = expression 


See Also EQU 


Remarks 

• SET and equals (=^ are interchangeable 

• Values assigned by a SET directive may be re-assigned at any time. 

• The Assembler does not allow the assigned expression inSET directive to 
contain forward references. If ^ET cannot be evaluated as it is currently 
defined, an error is generated. 

• If the symbol itself is used before it is defined, a warning is generated, and it is 
assigned the value determined by the preliminary pass of the Assembler. 

• The symbol in aSET directive does not assume the type of the operand. It is, 
therefore, better suited to setting local values, such as in macros, rather than in 
code with a relative start position, such as a SECTIOMonstruct, which may 
cause an error - seeExamples. 


Examples 

Loopcount 

set 

0 


GrandTotal 

= 

SubTotalA+SubTotalB 


xdim 

set 

Bsize<<SC 
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The following example will encrypt the string passed as the macro parameter. 


ebb 

macro 

string 


Ic 

rept 

0 

strlen (\string) 


cc 

substr 

lc+1, lc+1, \string; 

extract one 
character into 
label cc 


db 

' \cc' " ($A5+lc) 

encrypt the 
character stored 
in cc and define 
in memory 

Ic 

endr 

endm 

lc+1 

; increment counter 
; do for all chars 
in string 
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EQUS 

Description Assigns a text or string variable to a symbol. 

Syntax symbol name EQUS "text" 

symbol name EQUS 'text' 
symbol name EQUS symbol name 

See Also EQU, SET 

Remarks 

• Textual operands are delimited by double or single quotes. If it is required to 
include a double quote in the text string, delimit with single quotes or two double 
quotes; similarly, to include a single quote in the text, delimit with double quotes 
or two single quotes - see examples below. 

• If delimiters are omitted, the Assembler assumes the operand to be the symbol 
name of a previously defined string variable, the value of which is assigned to the 
new symbol name. 

• Point brackets, { and } are special delimiters used in Macros - seMACRO 
directive specification, chapter 5. 

• Symbols equated with th^lQUS directive can appear at any point in the code, 
included as part of another text string. If there is the possibility of confusion with 
the surrounding text, a backslash (\) may be used before the symbol name and if 
necessary, after it, to ensure the expression is expanded correctly. See examples 
below. 


Examples 


Sinquote 

equs 

‘What'''s the point? ’ 

S inquote 

equs 

“What's the point? ” 

Doubquote 

equs 

“Say” “Hello” “and go 

Doubquote 

equs 

‘Say “Hello” and go’ 

Program 

equs 

“ABS V 1.2” 

Qtex 

equs 

“What's the score? ” 


db 

“Remember to assemble 
\_filename ”, 0 
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z 

equs 

“123” 


dw 

z + 4 

converts 

to 



dw 

123 + 4 

whereas the following expression needs backslashes to be 

expanded 

correctly 


dw 

number\z\a 

converts 

to 



dw 

numberl23a 

SA 

equs 

‘St art Address ’ 


dw 

\SA\4 

converts 

to 



dw 

StartAddress4 
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EQUR 

Description Defines a symbol as an alternative for a register. 

Syntax symbol name EQUR register name 

See Also REG 

Remarks 

• The major use of theEQUR directive is to improve the overall readability of the 
source code. 

• In order that the Assembler can evaluate the expression correctly, dots are not 
allowed as part of the symbol name of aEQUR (see example below). 

Examples Iw tl, RGBinds (a2) 

This could be re-written usin^QUR's, as follows: 

Red equr tl 

Green equr a2 

Iw Red, RGBinds (Green) 
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Description 

Syntax 

See Also 
Remarks 

Examples 


Assigns the value of the RS variable to the symbol, and advances thEs counter by 

the number of bytes, half-words or words, specified hvunt. 


symbol name Rsizc count 


where size is b 

h 

w 


byte (8 bits) 
halfword (16 bits) 
word (32 bits) 


(if size is not specified,w is assumed) 


RSSET, RSRESET 


• This directive, together with the following two associated directives, operate on 
or with the Assembler variable. RS. which contains the current offset. 



rsreset 

Icon_no 

rb 

1 

Dropcode 

rh 

1 

Actcode 

rh 

1 

Act name 

rb 

10 

Ob jpos 

rw 

1 

Artlen 

rb 

0 


After each of the first fivdlS equates, the RS pointer is advanced; the values for 

each equate are as follows: 
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Icon_no 

0 

(set to zero by RSRESET) 

Dropcode 

1 


Actcode 

boundary) 

4 

(Automatic Alignment set, advances the pointer to Alignment 

Actname 

6 


Ob jpos 

16 


Artlen 

20 



The lastrb does not advance the RS pointer, since a count of zero is equivalent to 

an EQUATE to the RS variable. 


RSSET 


Description 


Syntax 


See Also 


Remarks 


Examples 


Assigns the specified value t o RS variable. 

RSSET value 
Rsize, RSRESET 

This directive is normally used when the offsets are to start at a value other than zero. 
See the Rsize directive 
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RSRESET 

Description Sets the RS variable to zero. 

Syntax RSRESET [value] 

See Also Rsize, RSSET 

Remarks 

• Using this direetive is the normal way to initialise the RS eounter at the start of 
a new data strueture. 

• The optional parameter is provided for eompatibility with other assemblers; if 
present, RSRESET behaves like theRESET direetive. 

Examples See the Rsize direetive 
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Data Definition 


The directives in this section are used to define data and reserve space. 


• Dsize 

• DC size 

• DSsize 

• HEX 

• DATA 

• DATASIZE 

• IEEE32 

• IEEE64 
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Dsize 

Description 

Syntax 

See Also 
Remarks 


Examples 

Notes 


This directive evaluates the expressions in the operand field, and assigns the results to 
the preceding symbol, in the format specified by the size parameter. Argument 
expressions may be numeric values, strings or symbols. 


symbol name Dsize 


expression, . . , expression 


where. j'/zc is b 

h 

w 


byte (8 bits) 
half word 
word 


DC size 


• Textual operands are delimited by double or single quotes. If it is required to 
include a double quote in the text string, delimit with single quotes or two double 
quotes; similarly, to include a single quote in the text, delimit with double quotes 
or two single quotes - see examples below. If delimiters are omitted, the 
Assembler assumes the operand to be the symbol name of a previously defined 
string variable, the value of which is assigned to the new symbol name. 

• When the Automatic Alignments sembler option (/AE) is in force, directives for 
half word and word ensure that the program counter is aligned to the next word 
boundary. 


Hexvals 

dh 

$80d, $a08, 0, $80d, 0 

Coords 

dw 

-15,46 

Pointers 

dw 

StartMarker, EndMarker 

ErrorMes 

db 

"Eile Error", 0 


If the Assembler encounters a parameter that is out-of-range, an error is flagged; the 
following statements will produce errors: 


db 

257 

db 

-129 

dh 

66000 

dh 

-33000 


© SN Systems Ltd 




Page 4-14 


General Assembler Directives 


Nintendo 64 


DCsize 

Description 

Syntax 

See Also 
Remarks 

Examples 


This directive generates a block of memory of the specified length, containing the 
specified value. 


DCsizdength,value 


where size is b 

h 

w 


byte (8 bits) 
halfword (16 bits) 
word 


Dsize 


When the Automatic Alignmenlssembler option (/AE) is in force, DCB directives 
for half word and word ensure that the program counter is aligned to the next word 


boundary. 



deb 

256, $7F 

; generates 

256 bytes eontaining 

dew 

64, $12345678 

; generates 
$12345678 

54 words eontaining 
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Dssize 

Description Allocates memory to thesymbolof the specif iedlength and initialises it to zero. 


Syntax 

symbol name DSsize 

length 


where size is b 

byte (8 bits) 


h 

half word (16 


w 

word 

See Also 

Dsize, DC size 



Remarks 

• When the Automatic Alignments sembler option (/AE) is in forcePS directives 
for word and long wordcnsmc that the program counter is aligned to the next 
wordboundary. 

• If this directive is used to allocate memory in Group/Section with theBSS 
attribute, the reserved area will not be initialised - sddroups and Sections, 
chapter 8. 


Examples List dsw 64 

reserves an area 64 words long, and sets it to zero. 
Buffer dsb 1024 

reserves a Ik bytes area, and sets it to zero. 
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HEX 

Description 

Syntax 
See Also 
Remarks 

Examples 


This directive takes a list of hex digits as an argument and assigns the resulting value 
to the preceding symbol. It is intended as a quick way of inputting small hex 
expressions. 


symbol name HEX hexlist 


INCBIN 


Data stored as HEX is difficult to read, less memory-efficient and causes more work 
for the Assembler. Therefore, it is suggested that thHEX statement is used for 
comparatively minor data definitions only. To load larger quantities of data, it is 
recommended that the data is stored in a file, to be INCLUDEd as a binary file at 
runtime - seeinclude Files, chapter 4. 


HexStr hex 100204FF0128 

is another way of writing 

HexStr db $10, $02, $04, $FF, $01, $28 
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DATASIZEand DATA 

Description Together, these directives allow the programmer to define values between 1 and 256 
bytes long (8 to 2048 bits). The size of thOATA items must first be defined by a 
DATASIZE directive. 


Syntax DATASIZE size 

DATA value, value 

where value is a numeric string, in hex or decimal, optionally preceded by a minus 
sign. 

See Also IEEE32, IEEE64 

Remarks If a value specified in theDATA directive converts to a value greater than can be 
held msize specified byDATASIZE, the Assembler flags an error. 

Examples datasize 8 

data 
data 


IEEE32 and IEEE64 

Description These directives allow 32 and 64 bit floating point numbers to be definedIBEE 
format. 


Syntax IEEE32 fp. value 

IEEE64 fp. value 


See Also DATA, DATASIZE 


Examples ieee32 1.23,34el0 

ieee64 123456 . 7654321e-2 


$123456789ABCDEF0 
-1, $FFFFFFFFFFFF 
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Controlling Program Executio n 


The directives in this section are used to alter the state of the program counter and 
control the execution of the Assembler. 


• ORG 

• CNOP 

• OBJ 

• OBJEND 
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ORG 

Description 

Syntax 

See Also 
Remarks 

Examples 


The ORG directive informs the Assembler of the location of the code in the target 
machine. 


ORG addressf, parameter] 

where is a previously-defined symbol, or a hex or decimal value, optionally 

preceded by a question mark 0?and followed by a (target-specific) numeric 
parameter. 


OBJ, OBJEND, GROUP, SECTION 


• If a link file is output, thdORG directive must not be used - sedGroups and 
Sections, chapter 8. 

• If the program containsSECTIONs, a singleORG is allowed, and it must 
precede allSECTION directives. If the program does not utilise thSECTION 
construct, it may contain multiplORG's. 



org 

$100 

Begin 

move . w 

sr, - (A7) 

Program 

equ 

$4000 


org 

Program 
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CNOP 


Description Resets the program counter to a specif iedtff set from the specifieds'/zc boundary. 


Syntax CNOP ojf set, size boundary 

Remarks In code containingSECTIONs, the Assembler does not allow the program counter 
to be reset to a size boundary greater than the alignmeMready set for that section. 
Therefore, a CNOP statement with a size boundary of 2 is not allowed in a section 
that is byte- aligned. 

Examples section prime 

Firstoff = 512 

Firstsize = 2 

cnop Firstoff , Firstsize 

sets the program counter to 512 bytes above the next word boundary. 
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OBJ and OBJEND 


Description OBJ forces the code following it to be assembled as if it were at the specified 
address, although it will still appear following on from the previous code. 

OBJEND terminates this process and returns to thdORG'd address value. 


Syntax 


OBJ address 

OBJEND 


See Also ORG 


Remarks 

• The OBJ - OBJEND construct is useful for code that must be assembled at one 
address (for instance, in a ROM cartridge), but will be run at a different address, 
after being copied there. 

• Code blocks delimited bjOBJ - OBJEND cannot be nested. 


Examples 


org 

$100 

dw 

-k 

dw 

k 

ob j 

$200 

dw 

k 

dw 

k 

ob jend 

dw 

k 

dw 

k 


The above code will generate the following sequence of words, starting at address 

$ 100 : 


$100 

$104 

$200 

$204 

$110 

$114 
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Include Files 


The source code for most non-trivial programs is too large to be handled as a single 
file. It is normal for a program to be constructed of subsidiary files, which are called 
together during the assembly process. 

The directives in this section are used to collect together the separate source files and 
control their usage; also discussed are operators to aid the control of code to be 
assembled fromINCLUDEd files. 


• INCLUDE 

• INCBIN 

• DEE 

• REF 
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INCLUDE 


Description As the source code for most no-trivial programs is too large to be handled as a single 
file, it is normal for a program to be constructed of subsidiary files, which are called 
together during the assembly process. This directive tells the Assembler to draw in 
and process another source file, before resuming the processing of the current file. 

Syntax INCLUDE filename 

where filename is the name of the source file to be processed, including drive and 
path identifiers - seeNote. The filename may be surrounded by quotes, but they will 
be ignored. 

See Also INCBIN 


Remarks 


Traditionally, there will be one main file of source code, which contalMCLUDE's 
for all the other files. 


The /j switch can be used to specify a search path fdNCLUDEd files - see 

Assembler Option^ chapter 9. 


Examples A typical start to a program may be: 


codestart 


section 

short 1 

jmp 

entrypoint 

db 

_hours , _minutes 

db 

_day,_month 

dh 

_year 

include 

varsl . s 

section 

short2 

include 

vars2 . s 

section 

code 

include 

graph 1 . s 

include 

graph2 . s 
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include maths . s 
include trees. s 
include tactics.s 


entrypoint 11 
Iw 


to, 8 

aO, fred 


Note: Since a path name contains backslashes, the text in the operand of an 
INCLUDE statement may be confused with the usage of text previously 
defined by an EQUS directive. To avoid this, a second backslash may be used 
or the backslash may be replaced by a forward slash. 
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INCBIN 

Description 

Syntax 

See Also 
Remarks 


Examples 


Informs the Assembler to draw in and process binary data held in another source file, 
before resuming the processing of the current file. 


symbol INCBIN filename [, start, length] 

• filename is the name of the source file to be processed, including drive and path 
identifiers Optionally, the filename may be surrounded by quotes, which will be 
ignored; 

• start and length are optional values, allowing selected portions of the specified 
file to be included. 


INCLUDE, HEX 


• This directive allows quantities of binary data to be maintained in a separate file 
and pulled into the main program at assembly time; typically, such data might be 
character movement strings, or location co-ordinates. The Assembler is passed no 
information concerning the type and layout of the incoming data. Therefore, 
labeling and modifying thlNCBINed data is the responsibility of the 
programmer. 

• The/j switch can be used to specify a search path fciNCLUDEd files - see 
Assembler Options, chapter 9. 


Charmove incbin d: \source\charmov.bin 

Note: Since a path name contains backslashes, the text in the operand of an INCBIN 
statement may be confused with the usage of text previously defined by an 
EQUS directive. To avoid this, a second backslash may be used or the 
backslash may be replaced by a forward slash. 

Thus, include f:\source\charmov.bin 

may be re-written as 

include d: WsourceWcharmov.bin or 
include d: /source/charmov.bin 
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Note 


REF 

Description 

Syntax 

Remarks 

Examples 


The nominated file may be accessedelectively, by specifying a position in the file, 
from which to start reading, and dength. Note that: 

• if start is omitted, the INCBIN commences at the beginning of the file; 

• if the length is omitted, the INCBIN continues to the end of the file; 

• if both start and length are omitted, the entire file UNCBINed. 


REF is a special operator to allow the programmer to determine which segments of 
code are to beINCLUDEd. 


[~]REF(symbol) 

The optional preceding tilde (~) is synonymous wiffiOT. 


REF is true if a reference has previously been encountered for the symbol in the 
brackets. 



if 

ref (Links) 

Links 

Iw 

rl, 8 (aO) 


jr 

ra 


endif 



The Links routine will be assembled if a reference to it has already been encountered. 
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DEF 

Description Like the REF operator, DEF is a special function. It allows the programmer to 
determine which segments of code have already bedNCLUDEd. 

Syntax [~]DEF(symbol) 

The optional preceding tilde (~) is synonymous wiMOT. 

Remarks DEF is true if the symbol in the brackets has previously been defined. 

Examples if ~def (loadadr) 

loadadr equ $1000 

execadr equ $1000 

relocadr equ $80000-$300 

endc 


The address equates will be assembled if load_addr has not already been defined. 
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Controlling Assembl y 


The following directives give instructions to the Assembler during the assembly 
process. They allow the programmer to select and repeat sections of code: 


• END 

• IF 

• ELSE 

• ELSEIF 

• ENDIF 

• CASE 

• ENDCASE 

• KEPT 

• ENDR 

• WHILE 

• ENDW 

• DO 

• UNTIL 
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END 


Description The END directive informs the Assembler to cease its assembly of the source code. 


Syntax 


END [address] 


See Also REGS 


Remarks 

• The inclusion of this directive is mostly cosmetic, since the Assembler will cease 
processing when the input source code is exhausted. 

• The optional parameter specifies an initial address for the program. See also the 
REGS statement, in the section -Target-Related Directives, chapter 4. 


Example startrel 


Iw 

to, (aO) 

addu 

r3, r 2, rl 

jr 

ra 

end 



IF, ELSE, ELSEIF, ENDIF, ENDC 


Description These conditional directives allow the programmer to select code for assembly. 


Syntax 

IF 

ELSE 

[~]expression 


ELSEIF 

ENDIF 

ENDC 

[~]expression 


See Also CASE 
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Remarks 


Examples 


• The ENDC and END IF directives are interchangeable. 

• If the ELSEIF directive is used without a following expression, it acts the same 
as an ELSE directive. 

• The optional tilde, preceding the operand expression, is synonymous wM9T. 

Its use normally necessitates the prudent use of brackets to preserve the sense of 
expression. 



if 

Nintendo 1 

sec_dir 

equ 

2 


elseif 

Target 

sec_dir 

equ 

1 


else 


sec_dir 

equ 

endif 

3 


if 

-usesquare 

round 

macro 

addu 

endm 

\1,\2,\3 


elseif 


round 

macro 

endm 

endc 


Idimm 

macro 

dest , imm 


if 

(\imm>- 

32768) & (\imm<32768 ) 


addiu 

\dest, rO, \imm 


else 

lui \dest, (\imm)>>16 


if 

(\imm) &$ff ff 


ori 

endif 

endif 

endm 

\dest,\det, (\imm)&$ffff 
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CASE and ENDCASE 


Description The CASE directive is used to select code in a multiple-choice situation. TKMSE 
argument defines the expression to be evaluated; if the argument(s) after th^uals 
sign are true, the code that follows is assembled. Thequals-questionmavk case is 
selected if no previous case itrue. 

Syntax CASE expression 

=expression[, expression] 

=? 

ENDCASE 


See Also IF conditionals 


Remarks In the absence of aequals-question mark(=l) case, if the existing cases are 
unsuccessful, the case-defined code is not assembled. 


Examples The following is an alternative for the example listed under tIE directive - see 
chapter 4. 

Target equ Nintendol 


case Target 

=Nintendol 
sec_dir equ 2 

=Nintendo2 
sec_dir equ 1 

=? db "New Version", 0 

sec_dir equ 3 

endcase 
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KEPT, ENDR 


Description These directives allow the programmer to repeat the code between tlftEPT and 
ENDR statements. The number of repetitions is determined by the value 

Syntax REPT count 

ENDR 

See Also DO, WHILE 

Remarks When used in a MacroREPT is frequently associated with th^ARG function. 

Examples rept 12 

dh 0 , 0 , 0 , 0 

endr 


ebb 

macro 

string 

Ic 

= 

0 


rept 

strlen (\string) 

cc 

substr 

lc+1, lc+1, \string 


db "\cc" 

" ($A5+lc) 

Ic 

endr 

endm 

lc+1 
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WHILE, 

Description 


Syntax 


See Also 


Remarks 


Examples 


ENDW 


These directives allow the programmer to repeat the code between the WHILE and 
ENDW statements, as long as the expression in the operand hoXime. 


WHILE expression 

ENDW 


REPT, DO 


Currently, any string equate substitutions in thWHILE expression take place once 
only, when theWHILE loop is first encountered - sedVote below for the 
ramifications of this. 


MultP 

equ 

16 

Indie 


MultP 


• le 

Indie>l 


Iw 

rl, term (aO ) 

Indie 

endw 

Indie-1 


Note: Because string equates are only evaluated at the start of thWHILE loop, the 
following will not work: 


s equs "x" 

while strlen 

deb "\s",0 

s equs "\s\x" 

endw 


"\s") 


< 4 
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To avoid this, set a variable each time round the loop to indicate that looping should 
continue: 


s equs 

looping = 

while 

db 

s equs 

looping = 

endw 


"X" 

-1 

looping 

"\s", 0 

"\s\x" 

strlen("\s") < 4 


DO, UNTIL 


Description These directives allow the programmer to repeat the code between tlDO and 
UNTIL statements, until the specified expression becomesMC. 

Syntax DO 

UNTIL expression 

See Also REPT, WHILE 


Remarks Unlike the WHILE directive, string equates in aiLNTIL expression will be re- 

evaluated each time round the loop. 


Examples 


MultP 

egu 

16 

Indie 

= 

MultP 


do 



Iw 

rl, term (aO ) 

Indie 

= 

Indie-1 


until 

Indie<=l 
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Target-Related Directive 


The following directive allows the programmer to specify certain initial parameters 
the target machine: 

• REGS 
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REGS 

Description 

Syntax 

Remarks 

Example 


This directive allows the programmer to specify certain initial parameters in the target 
machine. If aCPE file is produced or object code output is directed to the target, the 
REGS directive specifies the contents of the registers at the start of code execution. 

REGS regcode=expression[,regcode=expression ] 

where regcode is the mnemonic name of a register, such asl, PC. 


This directive is not available for relocatable code which is specific to the target or 
pure binary code. 


regs pc = SN ENTRY POINT 


Register assigns can be declared on one line, separated by commas. 
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CHAPTER 5 

Macros 


The Assembler provides extensive macro facilities; these allow the programmer to 
assign names to complete code sequences. They may then be used in the main 
program like existing assembler directives. 

This chapter discusses the following topics, directives and functions: 

• MACRO, ENDM 

• MEXIT 

• Macro Parameters 

• SHIFT, NARG 

• MACROS 

• PUSHP, POPP 

• PURGE 

• TYPE 


© SN Systems Ltd 





Page 5-2 


Macros 


Nintendo 64 


MACRO, ENDM, MEXIT 

The Assembler provides extensive macro facilities; these allow the programmer to 
assign names to complete code sequences. They may then be used in the main 
program like existing assembler directives. 

Description A macro consists of the source lines and parameter place markers between the 

MACRO directive and theENDM. The label field is the symbolic name by which the 
macro is invoked; the operand allows the entry of a string of parameter data names. 

When the assembler encounters a directive consisting of and optional 
parameters, the source lines are pulled into the main program and expanded by 
substituting the place markers with the invocation parameters. The expansion of the 
macro is stopped immediately if the assembler encounterMEXIT directive. 

Syntax Label MACRO [symbol,. .symbol] 

MEXIT 

ENDM 


See Also MACROS 


Remarks 

• Note that the invocation parameter string effectively starts at the character after 
the macro name, that is, thodot (.) character. Text strings, as well asb, .w and .1 
are permissible parameters - seParameters below. 

• Control structures within macros must be complete. Structures started in the 
macro must finish before th£NDM; similarly, a structure started externally must 
not be terminated within the macro. To imitate a simple control structure 

from another assembler, a short macro might be used - sd\dACROS below. 

Examples remove macro 

dh -2,0,0 

endm 


Form macro 

if strcmp ( ' \1 ' , ' 0 ' ) 

dh 0 

else 

dh \l-FormBase 

endif 

endm 
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Macro Parameters 


Parameters Macro parameters obey the following rules: 

• The parameters listed on the macro invocation line may appear at any point in the 
code declared between thdMACRO andENDM statements. Each parameter is 
introduced by abackslash(\); where this may be confused with text from an 
EQUS, a backslash may also follow the parameter. 

• Up to thirty two different parametersare allowed, numberedO to \31. \0 is a 
special parameter which gives the contents of t\mze field of the macro directive 
when it was invoked, that is, the text after the point symbol (.) This includes not 
only.b, .h or .w, but also any text: 


Example zed macro 

\0 

endm 
zed. nop 

will generate a NOP instruetion. 

Instead of the\0 to \31 format, parameters can be given symbolic names, by their 
inclusion as operands to th^ACRO directive. The precedin^ackslash(\) is not 
mandatory; however, if there is the possibility of confusion with the surrounding text, 
a backslashmay be used before and after the symbol name to ensure the expression is 
expanded correctly: 


Example Position macro A, B, C, Pos, Time 

dh \Time* (\A*\Pos+\B*\Pos+\C*\Pos) 

endm 

Surrounding the operand of an invoked macro wit^eater thanandless than signs 
(<...>), allows the use of comma and space characters. 
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Example 


Example 


Credits macro 

dh \1,\2 

db \3 

db 0 

even 
endm 

Credits 11,10,<ABS, from Jones> 


• Continuation Lines- when invoking a macro, it is possible that the parameter list 
will become overlong. As with any directive statement, the line can be terminated 
by anampersand(&) and continued on the next line to improve readability. 


chstr macro 

rept 
db 

shift 

endr 

db 

even 

endm 

cheatstr chstr 


narg 

k_\l 

0 


i,c,a,n,b,a,r,e,l,y,& 
s, t , a, n , d, i, t 
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Special Parameters 

There are a number of special parameter formats available in macros, as follows: 

Converting Integers to Text 

The parameters Wand \$ replace the decimal (f or hex ($) value of the symbol 
following them, with their character representation. Commonly, this technique is used 
to access Run Date and Time: 

Example 

RunTime db "\#_hours : \#_minutes : & 

\#_seconds" 

this expands to the form hh:mm:ss, as follows 

RunTime db "21:08:49" 

Generating Unique Labels 

The parameter\@ can be used as the last characters of a label name in a macro. 

When the macro is invoked, this will be expanded to an underscore followed by a 
decimal number; this number is increased on each subsequent invocation to give a 
unique label. 

Example Slots macro 

add rl,r0,r0 
Iw rl, \1 
beq rll, rO, 1 

next\0 addiu f3,r0,l 

bgt 

dun\0 

endm 

Slots freeobl, numslotl 

Each time theSlots macro is used, new labels in the form next_001 and dun_001 will 
be generated. 
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Entire Parameter 

If the special parameteA_ (backslash underscore) is encountered in a macro, it is 
expanded to the complete argument specified on the macro invocation statement. 


Examples All macro 

db \_ 

endm 

All 1,2, 3, 4 

will generate 

db 1,2, 3, 4 

Control Characters 

The parameter\'^jc, where x denotes a control character, will generate the specified 
control character. 


Using the Macro Label 

The label heading the invocation line can be used in the macro, by specifying the first 
name in the symbol list of thMACRO directive to be an asterisk (^, and 
sub stitu ting \* for the label itself. However, the resultant label is not defined at the 
current program location. Therefore, the label remainmde/med unless the 
programmer gives it a value. 


Extended Parameters 

The Assembler accepts a set of elements, enclosed in curly brackets ${^o be 
passed to a macro parameter. ThdVARG function andSHIFT directive can then be 
used to handle the list: 


Example cmd 

cc 


macro 


equs 

{\1} 

rept 

narg (cc 

\cc 


shift 

cc 

endr 


endm 


jr 

ra 
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SHIFT, NARG 


Description These directives cater for a macro having a variable parameter list as its operand. The 
NARG symbol is the number of arguments on the macro invocation line; tSHIFT 
directive shifts all the arguments one place to the left, losing the leftmost argument. 


Syntax directive NARG 

SHIFT 

where NARG is a reserved, predefined symbol. 


See Also 

Extended Parameters 


Examples 

routes macro 



rept 

narg 


if 

strcmp ( ' \1 ' , 


dh 

0 


else 



dh 

\l-routebase 


endif 



shift 



endr 



endm 



routes 

0, gosouth_l 


This example goes through the list of parameters given to the macro and defines a 
half word of $0000 if the argument is zero or a 16 bit offset into the ‘routebase’ table 
of the given label. 
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MACROS 

Description The MACROS directive allows the entry of a single line of code as a macro, with no 
associatedENDM directive. The single line of code can be a control structure 
directive. 


Syntax Label MACROS [symbol,., symbol 

See Also MACRO 


Remarks The MACROS directive may be used to stand in for a single, complex code line. 

Often, the short macro allows the programmer to synthesise a directive from another 
assembler. Including thek option on the command line will cause several macros 
emulating foreign directives to be generated. 

Examples a = 0 ;a=0 do explosion 

; a=l do offset calculation 



if 

0 

boom 

macros 



jal 

else 

explosM 

boom 

macros 



Iw 

endif 

rl,blow up-tactbase (\1 
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PUSHP, POPP 


Description These directives allow text to be pushed into, and then popped from, a string 
variable. 


Syntax PUSHP string 

POPP string 


Remarks There is no requirement for thd*USH and correspondingPOPP directives to appear 
in the same macro. 


Examples makeframe macro stksize 

pushp \stksize 

sub sp, \stksize\l 

endm 


freeframe macro 

popp stksize 

add sp, \stksize 

endm 


This means the user does not have to specifytksize when using freeframe. The 
user must ensure that calls to makeframe and freeframe are balanced. 
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PURGE 

Description 

Syntax 

Remarks 

Examples 


The PURGE directive removes an expanded macro from the internal tables and 
releases the memory it occupied. 


PURGE macroname 


It you need to redefine a macro, it is not necessary to purge it first as this is done by 
the Assembler. 


HugeM 


macro 


dh 

\1 

dh 

\2 

dh 

endm 

\31 

HugeM 

paral, 103, faultlevel, & 


40, 50,para31 

purge 

HugeM 
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TYPE 


Description TYPE is a function used to provide information about a symbol. It is frequently used 
with a macro to determine the nature of its parameters. The value is returned as a 
word; the meanings of the bit settings are given below. 


Syntax 


TW^{symbol) 


The reply word can be interpreted as follows: 

BitO 

Symbol has an absolute value 

Bitl 

Symbol is relative to the start of the Section 

Bit 2 

Symbol was defined usin^ET 

Bit 3 

Symbol is a Macro 

Bit 4 

Symbol is a String Equate ^QUS) 

Bits 

Symbol was defined usin^QU 

Bit 6 

Symbol appeared in aiXREF statement 

Bit? 

Symbol appeared in aiXDEF statement 

Bits 

Symbol is a Function 

Bit 9 

Symbol is a Group Name 

Bit 10 

Symbol is a Macro parameter 

Bit 11 

Symbol is a short Macro MACROS) 

Bit 12 

Symbol is a Section Name 

Bit 14 

Symbol is a Register Eqate (EQUR) 
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CHAPTER 6 

String Manipulation Functions 


To enhance the Macro structure, the Assembler includes powerful functions for string 
manipulation. These enable the programmer to compare strings, examine text and 
prepare subsets. 

This chapter covers the following string handling functions and directive: 

• STRLEN 

• STRCMP 

• INSTR 

• SUBSTR 
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STRLEN 


Description A function which returns the length of the text specified in the brackets. 


Syntax STRLEN(string) 


See Also STRCMP 


Remarks The STRLEN function is available at any point in the operand. 


Examples Nummov macro 

rept 
Iw 
add 
sw 
add 
endr 
endm 

Nummov 12345 

The number of characters in the string is used as the extent of the loop. 


strlen (\1) 
r3, (aO 
aO, 4 
r3, (al) 
al, 4 
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STRCMP 

Description 

Syntax 
See Also 
Remarks 

Examples 


A function which compares two text strings in the brackets, and returtis<e if they 
match, otherwise it x&taxnf alse. 


^T'RCMP{stringl,string2) 


STRLEN 


When comparing two text strings, thSTRCMP function starts numbering the 
characters in the target texts from one. 


equ 

"Acs" 

if 

strcmp ("\Vers", "Sales" 

Ih 

vO,SalInd (aO) 

else 


if 

strcmp ("\Vers", "Acs") 

Ih 

vO, Acind (aO) 

else 


if 

strcmp ("\Vers", "Test") 

ih 

vO, Tstind (aO) 

endif 



endif 

endif 
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INSTR 

Description This function searches a text string for a specified sub-string. If the string does not 
contain the sub-string, the result of zero is returned; if the sub-string is present, the 
result is the location of the sub-string from the start of the target text. It is also 
possible to specify an alternate start point within the string via an optional parameter. 


Syntax 


INSTR 

{{starQstring, substring) 

See Also 

SUBSTR 



Examples 

Mess 

equs 

"Demo for Sales Dept" 



if 

Iw vO , 

else 

Iw vO , 

endif 

instr ("\Mess", "Sales" 
Salind (aO 

Acind (aO) 


Note: When returning the offset of a located sub-string, thBVSTR function starts 
numbering the characters in the target text from one. 
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SUBSTR 

Description 

Syntax 
See Also 
Remarks 

Examples 


This directive assigns a value to a symbol; the value is a sub-string of a previously 
specified text string, defined by thstort and end parameters. The^tort andend 
parameters will default to the start and end of the string, if omitted. 


symbol SUBSTR {start], {end\, string 

INSTR, EQUS 


When assigning a sub-string to a symbol, tl&UBSTR directive starts numbering the 
characters in the source text from one. 


"A short Sample String" 
9,14, "\Message" 

16, , "\Message" 

, 7, "\Message" 

, , "\Message" 

where Parti equals 5amp/e 
Part2 equalsStnng 
Parts equalsA short 


Message 
Parti 
Part2 
Parts 
Part 4 


equs 

substr 

substr 

substr 

substr 


The last statement is equivalent to aiEQUS assigning the whole of the original 
string to Part4. 


Cbb 

macro 

string 

cc 

= 

0 


rept 

strlen (\string) 

cc 

substr 

lc+1, lc+1, \string 


db 

'\cc' " ($A5+lc) 


lc+1 



endr 



endm 



Again, this is an example of encryption of a string. 
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CHAPTER 7 

Local Labels 


As a program develops, finding label names that are both unique and definitive 
becomes increasingly difficult. Local Labels ease this situation by allowing 
meaningful label names to be re-used. 

This chapter covers the following topics and directives: 

• Local Label Syntax and Scope 

• MODULE and MODEND 

• LOCAL 


© SN Systems Ltd 





Page 7-2 


Local Labels 


Nintendo 64 


Syntax and Scope 


Syntax 

• Local Labels are preceded by a local label signifier. By default, this is@nsign; 
however, any other character may be declared by using tl©ption in anOPT 
directive or on the Assembler command line - sefessembler Option^ chapter 9. 

• Local label names follow the general label rules, as specified in chapter 3. 

• Local labels are not de-scoped by the expansion of a macro. 


Scope The region of code within which a Local Label is effective is called5tS9pe. Outside 

this area, the label name can be re-used. There are three methods of defining the 
scope of a Local Label: 

• The scope of a local label is implicitly defined between two non-local labels. 
Setting a variable, defining an equate or RS value does not de-scope current local 
labels, unless the d option has been used in an OPT directive or on the Assembler 
command line - see Assembler Options, chapter 9.. 

• The scope of a Local Label can also, and more normally, be defined by the 
directives MODULE and MODEND - see chapter 7. 

• To define labels (or any other syimol type) for local use in a macro, the EOCAE 
directive can be used - see chapter 7.. 


Examples 

plot2 

lb 

to, loc (tl) 



nop 

subiu 

to, t2 



bne 

zero, to, 0chkl 



nop 

jal 

Icolor 



nop 

b 

setplot 


0chkl 

nop 



Setplot 

Plots 

set 




b 

0chkl 



nop 
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MODULE and MODEND 


Description Code occurring after aMODULE statement, and up to and including thMODEND 
statement, is considered to be module. Local labels defined in module can be re- 
used, but cannot be referenced outside thmodulds scope. A Local label defined 
elsewhere cannot be referenced within theurrent module 


Syntax 


MODULE 


MODEND 


See Also LOCAL 


Remarks 

• Modules can be nested. 

• The MODULE statement itself is effectively a non-local label and will de-scope 
any currently active default scoping. 

• Macros can contain modules or be contained in a ndole. A local label occurring 
in a module can be referred to by a macro residing anywhere within the module. 
A module contained within a macro can effectively provide labels local to that 
macro. 


Examples 


mystrcmp module 
move 
move 

01p Ibu 

add! 
Ibu 
addiu 
bne 
nop 
bnez 
nop 
li 

0diff jr 

nop 

modend 


t2, aO 
vO , zero 

to, 0 (t2) 

t2,t2, 1 
tl, 0 (a2) 
a2, a2, 1 

to, tl, 0dif f 

to, 01p 

vO, 1 ; true 

ra 

; mystrcmp 
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LOCAL 


Description The LOCAL directive is used to declare a set of macro-specific labels. 
Syntax LOCAL symbol.., symbol 


See Also MODULE 


Remarks 


The scope of symbols declared using thLOCAL directive is restricted to the 
host macro. 

The LOCAL directive does not force a type on the symbol set that makes up its 
operand. In practice, therefore, such symbols can be used as equates, string 
equates or any other type, as well as labels. 


Examples print 

macro 

string 


local 

my label 


jal 

stri ngprint 


nop 



db 

\string, 0 


cnop 

0,4 

my label 

endm 
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CHAPTER 8 

Structuring the Program 


Normally, the organisation of the memory of the target machine does not match the 
layout of the source files. The Assembler however, uses Groups and Sections to 
create a structured target memoryand relocatable program sections. 

This chapter covers the following topics and directives: 

• SECTION 

• GROUP 

• PUSHS and POPS 

• SECT and OFFSET 
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GROUP 

Description 

Syntax 


See Also 
Remarks 

Example 

Example 


This directive declares a group with up to seven group attributes. 


GroupName GROUP [Attribute,.. Attribute] 

where an attribute is one of the following - see below for descriptions: 

WORD 

BSS 

O^G{address) 

¥\LiE(filename) 

OBJ(address) 

SlZEisize) 

OYER(GroupNami) 


SECTION 


Group Attributes are interpreted as follows: 

WORD - the group may be accessed using absolute word addressing. Note that this 
will only have an effect if thow+ parameter has been used to allow optimisation to 
occur. 

Groupl group word 

BSS - no initialised data to be declared in thigroup. 

Groupl group bss 


ORG - sets the ORG address of thegroup, without reference to the othergroup 
addresses. If this attribute is omitted, th^roMp will be placed in memory, following 
on from the end of the prewiougroup. 
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Example 


Example 


Examples 


Example 


Example 



org 

$100 

G1 

group 


G2 

group 

org ($400) 

G3 

group 



will place the groups in the sequence G1,G2,G3 


FILE - outputs a. group, such as an overlay, to a its own binary file; other groups will 
be output to the declared file. 

Groupl group org ($400) , file ("charov.bin") 


OBJ - sets the group's OBJ address. Code is assembled as if it is running at tlOBJ 
address but is placed at the group'ORG address. If no address is specified then the 
OBJ value is the same as the group'ORG address. 

Groupl group org ($400) , obj ($1000) 

Group2 group org ($800) , obj () 

SIZE - specifies the maximum allowable size of tljaroMp. If the size exceeds the 
specified size, the assembler reports an error. 

Groupl group size (32768) 


OVER - overlays ihisgroup on the specifiedgroMp. Code at the start of the second 
group is assembled at the same address as the start of the first group. The largest of 
the overlaid groups' sizes is used as the size of each group. 


Note: It is necessary to use theFILE attribute to force different overlays to be 
written to different output files. 


Group2 group 


over (Groupl ) 
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SECTION 

Description This directive declares a logical code section. 

Syntax SECTION^/ze SectionNam^,Group] 

SectionName SECTION^/ze [Attribute,.. Attribute] 

The second format is a special case, designed to allow definition of a section with 
group attributes - see below for a description. 

See Also GROUP 


Remarks 


Unless the section has been previously assigned, the section will be placed in an 
unnamed default group, if thdjROUP name is omitted 

It is possible to define a section with group attributes. The assembler will 
automatically create a group with the section name preceded by a tildc)(and 
place the section in it. 


Example Sectl section bss 

definesSecti, with the BSS attribute, in a group called Sectl. 


• The size parameter can beb, h or w; if the parameter is omitted, the default size 
is word. When a size is specified on a section directive, alignmetotthat size is 
forced at that point The start of the section is aligned on a boundary based on 
the largest size on any of the entries to that section - in all modules in the case of 
linked code. 


Note: If a section is sized as byte, you cannot use thEVEN directive in the 

section. Furthermore, theCNOP directive cannot be used to re-align the 
Program Counter to a value greater than the alignment of the host section 
- See chapter 4. 
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• If sections are used to structure application code, only a singBRG directive 
can be used; this must precede all section definitions. Groups and Sections may 
have ORG attributes to position them. 

No ORG directives or attributes are permitted when producing linkable output. 
Within a group, sections are ordered in the sequence that the Linker encounters 
the section definitions. 

Example 


Sectionb 

one 

db 

1,2,3 

section 

two 

db 

10, 11, 12 

sectionb 

one 

db 

4,5 

section 

two 

db 

13, 14 


Will produce the following sections and bytes: 

one 1, 2, 3, 4, 5 

two 10,11,12,0,13,14 
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PUSHS and POPS 


Description These directives allow the programmer to open a new, temporary section then return 
to the original sectionPUSHS saves the current sectionPOPS restores it. 


Syntax 


PUSHS 




POPS 


Examples 

plotcomp 

Iw 

to, 8 (tl) 


passdl 

equ 

pushs 

section 

dw 

* 

do light 
passdl 



pops 



This example showsPUSHS and POPS being used to pass system information 
between sections, in the form of the location counter. 
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SECT and OFFSET 


Description The SECT function returns the address of the section in which the symbol in the 
brackets is defined. TheOFFSET function returns the offset value from the 
beginning of the section. 


Syntax 


SECT (expression) 

OFFSET (expressior^ 


Remarks 


If a link is being performed, thSECT function is evaluated when it is linked; if 
there is no link it will be evaluated when the second pass has finished. 

Likewise, if a link is being performed, tHDFFSET function is evaluated when it 
is linked; however, if there is no link thOFFSET will be evaluated during the 
first pass. 


Examples 

dh 

sect (Tablel) 


dh 

sect (Table2) 


dh 

offset (*) 
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CHAPTER 9 

Options, Listings and Errors 


This chapter completes the discussion of the Assembler and its facilities. It covers 
methods of determining run-time Assembler options, producing listings and error- 
handling, as well as passing information to the Linker: 


• OPT 

• Assembler Options 

• PUSHO and POPO 

• LIST and NOLIST 

• INFORM 

• FAIL 

• XREF, XDEF and PUBLIC 

• GLOBAL 
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OPT 

Description 

Syntax 
See Also 
Remarks 


Examples 


This directive allows Assembler options to be enabled or disabled in the application 
code. See ‘Assembler Options’ below for a full listing. 


OPT option,. .option 

PUSHO, POPO 


• An option is turned on and off by the character following the option code: 

+ (plus sign) = ON 
- (minus sign) = OFF 

• Options may also be enabled or disabled by using thO switch on the Assembler 
command line - see Command Line Syntax, chapter 2. 

opt an+,l:,e- 
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Assembler Options 


The following reference list shows the default settings for the various options and 
optimisations available during assembly. More detailed descriptions are given below. 


Option 

Description 

Default 

AE 

Enable Automatic Alignment Mode 

On 

AN 

Enable Alternate Numeric mode 

Off 

AT 

Allow Assembler to use temporary Register 

On 

C 

Activate/ Suppress Case sensitivity 

Off 

D 

Allow EQU or SET to descope local labels 

Off 

E 

Print lines containing errors 

On 

H 

Automatic hazard removal (insert NOP) 

Off 

Ljc 

Substitute x for Eocal Eabel signifier 

Off 

M 

Enable/disable macro instructions 

On 

N 

Insert NOP in branch delay slots 

Off 

R 

Allow $ prefixed register names 

Off 

S 

Handle equated names as labels 

Off 

T 

Automatically truncate values in db/dh/dw statements 

Off 

V 

Write Eocal Eabels to symbol file 

Off 

w 

Print warning messages 

On 

ws 

Operands may contain white space 

Off 

X 

AssumeXREFs in defined section 

Off 
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Option Descriptions 


AE - Automatic Alignment 

When using the word and long word forms c©C, DCB, DS and RS, enabling this 
option forces the program counter to the following boundary prior to execution. The 
default setting for this option iAE+. 

AN - Alternate Numeric 

The default setting for this option iAN- but setting it toAN+ allows the inclusion of 
numeric constants in Zilog)r Intel format, i.e. followed b}H, D or B to signifyHex, 
Decimal or Binary, e.g. 0F123H = $F123. See also the section on theRADIX 
directive - chapter 3. 

AT - Alternate Assembler to use Temporary Register 

Within MIPS standard format code, some instructions are not actually instructions 
but macros, for example: 

sw to, fred 

when assembled will produce the following: 

Lui at,fred>>!6 

sw to, fred&$f fff (at) 

This trashes the AT Register. 

Warnings will be generated when the AT Register is used if this option is setA(T+ 
but errors will be inserted if it is set to\.T-. 

The default setting isAT+. 

C - Case Sensitivity 

When this option is set toC+, the case of the letters in a label's name is significant; 
for instance, SHOWSTATS, ShowStats and showstats would all be legal. The 
default setting isC-. 

D - Descope Local Labels 

The default setting for this option iD- but if it is set toD+, local labels will be 
descoped if auEQU or SET directive is encountered. 

E - Error Text Printing 

If this option is enabled, the text of the line which caused an Assembler error will be 
printed together with the host file name and line number. The default setting for this 
option is E+. 
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H - Automatic Hazard Removal 

If this option is set to the defaulH-, the Assembler will warn the user of any pipline 
hazards. If it is set toH+, it will insert an NOP into the code. Note that this does 
not apply to instructions following returns at the end of subroutines. 

L- Local Label Signifier 

Local labels are signified by a preceding AT sigris^ ). This option allows the use of 
the character following the option letter as the signifier. Thus;Lvould change the 
local label character to a colon :()• L+ andL- are special formats that toggle the 
character between ddot (+) and an @ sign(-). The default setting isL-. 

M - Enable/Disable Macro Instruction 

Set this option toM- and errors will be given on macro instructions, e.g. the 
following code: 

li r2, $587329 

will expand to the following sequence: 

lui r2, $58 

ori r2, $7329 

Set it to the defaultM+ and the same code will generate an error. 

N - Generate an NOP in Branch Delay Slots 

The default setting for this option iN- but set it to N+ and an NOP will be 
automatically inserted after all branch instructions. 

R - Allow $ prefixed register names 

R+ will allow the $ prefixed versions of the register names to be used but will disable 
the use of $ to prefix hexadecimal constants. 

S - Treat Equated Symbols as Labels 

The default setting for this option iS- but set it to S+ and disassembly will treat 
equates as labels rather than just values. 

W - Print warning messages 

When this option is set to the default setting oW+, the Assembler will identify 
various instances where a warning message would be printed but assembly will 
continue. Disabling th^ option will suppress the reporting of warning messages. 

WS - Allow white spaces 

The default setting for this option iWS- but if it is set toWS+, operands may 
contain white spaces. Thus, the statement: 

dc . 1 1+2 

defines alongwordof value 1 withWS set Off, and alongwordof value 3 withWS 
set to On. 
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X - XREFs in defined section 

The default setting for this option iX- but if it is set toX+, XREFs are assumed to 
be in the section in which they are defined. This allows optimisation to absolute word 
addressing to be performed provided that the section is defined with tWORD 
attribute or is in aGroup with the WORD attribute. 
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PUSHO and POPO 


Description The PUSHO directive saves the current state of all the assembler optionPjOPO 
restores the options to their previous state. They are used to make a temporary 
alteration to the state of one or more options. 


Syntax 


PUSHO 





POPO 



See Also 

OPT 




Examples 


pusho 


; save options state 



opt 

WS+, c+ 

; change options state 


SetAlts 

= 

height * time 



SETALTS 

dh 

256 * SetAlts 



popo 


; restore 

previous state 


LIST and NOLIST 


Description The NOLIST directive turns off listing generation; thLIST directive turns on the 
listing. 


Syntax NOLIST 

LIST indicator 

where indicator is a plus sign (+) or a minus sign (-). 
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Remarks 

• If a list file is nominated, either by its inclusion on the Assembler command line, 
or in the Assembler’s environment variable listing will be produced during the 
first pass. 

• The Assembler maintains ^current listing status variable, which is originally set 
to zero. List output is only generated when this variable is zero or positive. The 
listing directives affect the listing variable as follows: 

• NOLIST sets it to - 1 ; 

• LIST, with no parameter, zeroises it; 

• LIST + adds 1; 

• LIST - subtracts 1. 


Examples Directive 

nolist 
list - 
list 
list - 
list - 
list + 
list + 


Status Listing produced? 


-1 

no 

-2 

no 

0 

yes 

-1 

no 

-2 

no 

-1 

no 

0 

yes 


Note: The Assembler automatically suppresses production of listings during macro expansion 
and/or for unassembled code because of a failed conditional. 


These actions can be overridden by: 

• including the /M option on the Assembler command line to list expanding 
macros; 

• including the /C option on the Assembler command line to list conditionally 
ignored code - see Command Line Syntax, chapter 2. 


© SN Systems Ltd 




Nintendo 64 


Options, Listings and Errors 


Page 9-9 


INFORM and FAIL 


Description The INFORM directive displays an error message contained in text which may 

optionally contain parameters to be substituted by the contents of expressions after 
evaluation. Further Assembler action is based upon the state of severity. TBAIL 
directive is a pre-defined statement, included for compatibility with other Assemblers. 
It generates an “Assembly Failed” message and halts assembly. 


Syntax INFORM severity,text[,expression^ 

FAIL 


Remarks 

• These directives allow theprogrammer to display an appropriate message if an 
error condition is encountered which the Assembler does not recognise. 

• Severity is in the range 0 to 3, with the following effects: 

0 : the Assembler simply displays the text; 

1 : the Assembler displays the text and issues a warning; 

2 : the Assembler displays the text and raises an error; 

3 : the Assembler displays the text, raises a fatal error and halts the assembly. 

• Text may contain the parameter^d, %h and %s. They will be substituted by 
the decimal, hex or string values of the following expressions. 


Examples 


TableSize 

equ 

TableEnd-TableStart 

MaxTable 

equ 

512 


if 

Tables ize>MaxTable 


inform 

0, "Table starts at %h and& 
is %h bytes long",& 
TableStart , TableSize 


inform 

endif 

3, "Table Limit Violation" 
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XDEF, XREF and PUBLIC 


Description If several sub-programs are being linked, u^DEF, XREF and PUBLIC to refer to 
symbols in a sub-program which are defined in another sub-program. 


Syntax 


XDEF symbol[,symboI\ 

XREF symboI[,symboI\ 

PUBLIC on 

PUBLIC off 


Remarks 

• In the sub-program where symbols are initially defined, tSdlEF directive is 
used to declare them as externals. 

• In the sub-program which refers the symbols, thXREF directive is used to 
indicate that the symbols are in another sub-program. 

• The Assembler does not completely evaluate an expression containing an 
XREFed symbol; however, resolution will be effected by the linker. 

• The PUBLIC directive allows the programmer to declare a number of symbols as 
externals. With a parameter of on, it tells the Assembler that all further symbols 
should be automaticall^DEFed, until aPUBLIC off is encountered. 


Examples Sub-programA contains the following declarations : 

xdef Scores, Scorers 

The corresponding declarations in sub-prograrfi are: 

xdef PointsTable 

xref Scores, Scorers 


Origin 

public 

on 

MainChar 

Force 

dh 

speed*origin 

Rebound 

dh 

45*angle 


public 

off 
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GLOBAL 

Description 

Syntax 
See Also 
Remarks 


The GLOBAL directive allows a symbol to be defined which will be treated as either 
an XDEF or an XREF. If a symbol is defined aGLOBAL and is later defined as a 
label, it will be treated as aiXDEF. If the symbol is never defined, it will be treated 
as an XREF. 


GLOBAL symboJ[,symboJ] 

XREF, XDEF, PUBLIC 


This is useful in header files because it allows all separately assembled sub-programs 
to share one header file, defining all global symbols. Any of these symbols later 
defined in a sub-program will bXDEFed, the others will be treated a^REFs. 
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CHAPTER 10 

Debugger for Windows 95 

Introduction 

The Debugger for Windows 95 takes advantage of the new range of 32-bit operating 
systems available for PCs; it provides full source level as well as traditional symbolic 
debugging and supports and enhances all the power of the DOS-based version plus 
the advantages of a multi-tasking GUI environment. 

It helps you to detect, diagnose and correct errors in your programs via the step and 
trace facilities, with which you can examine local and global variables, registers and 
memory. 

Breakpoints can be set wherever you need them at C and Assembler level and if 
required, these breaks can be made conditional on an expression. Additionally, 
selected breakpoints can be disabled for particular runs. 

The Debugger employs drop-down menus, tool buttons, keyboard shortcuts and pop- 
up menus to help you debug quickly and intuitively. 

Projects 

The Debugger uses Projects to group together details of Files, Targets, Units, Views 
and other settings and preferences. All this information is saved and made available 
for your next debugging session. 

Views 

The Debugger offers the functionality of splitting the screen into a number of Panes, 
each displaying discreet or linked information. This information is available within a 
View, or document window (MDI Child). Each View can be split horizontally or 
vertically into the number of Panes you require and each Pane can be set to show a 
specific type of information. 

You can have as many combinations of either tiled Panes or overlapping Views as 
you choose. 

Your choice of Views depends on the level at which you are debugging. For 
example, it is appropriate to use a Register Pane for assembler debugging and a Local 
Pane when debugging in C. 
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Individual Views can be saved on disk for subsequent use in other Projects. 

However, when you close the Debugger and then re-start a session, your previous 
screen set-up will initially be displayed automatically. 

Colour Schemes 

To aid identification, aseparate colour scheme can be allocated to the Views used by 
each Unit that you reference. Alternatively, the same colour can be allocatedaH 
Views. 

Files 

The Symbol Files you require are located and loaded by the Debugger and the 
relevant CPE and Binary Files are downloaded to the Target. Where a multi-unit 
system is in use you must also specify the Unit where Symbol and Binary Files are to 
be loaded. 

Dynamic Update 

Changes in memory are highlighted on each display update, showing which areas of 
memory are being altered as the Target is being run and you are stepping and tracing 
your code. 

The following topics are discussed in this chapter: 


On-line Help 
Installing the Debugger 
Faunching the Debugger 
The File Server 

Connecting the Target and Unit 
Plug-In Components 
Project Management 
Debugger Productivity Features 
Views 
Panes 

Debugging Options 
Closing the Debugger 


© SN Systems Ltd 




Nintendo 64 


Windows 95 Debugger 


Page 10-3 


On-li ne Help Available For Th e Deb uf^er 


Help text describing the features covered in this chapter, can also be accessed on-line 
via the Help menu on the main menu. 

Selecting these options will result in the following: 

• Contents will display the Contents page of the help system in the left-hand side of 
the screen. Clicking any of the underlined topics will provide further information 
about the relevant subject. 

• Pane Types and the required Pane will directly access relevant text for the chosen 
Pane. 

• Installation will display installation procedures. 

• About will provide the Version Number. 

Within the on-line help system, clicking text withttotted underline will display a 
pop-up description but double-clicking text with solid underline will display another 
(linked) help page. 

The buttons at the top of the help text window can be used to facilitate the following: 

• Search and/or Find to locate a particular word or topic. 

• Back to re-display the previous page. 

• << and>> to display the previous and next page in the browse sequence, as 
outlined in the Table Of Contents. (See below). 

• Glossary to display an alphabetic listing of terms found in the help system. Click 
on any topic to obtain a pop-up definition. 

As well as accessing information via the Contents page, on-line help can also be 
located via the Table Of Contents in the right-hand area of the screen. This 
represents the subject areas of the help system as book icons. Double-click any icon 
to display titles of the individual pages which compose each ‘book’ . Double-click 
any of these pages and the text will be displayed in the left-hand side of the screen. 
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Installing The Debugger 


A Set-up program is used to install the Debugger; this is distributed via either of the 
following methods: 

• Full Release Files 

• Maintenance Patch Files 

Both methods are described in more detail below the Directory Structure. 


Directory Structure 

All the Files relating to the Windows software live in one directory tree. This tree 
can reside anywhere but it is probably easier to locate it on the root of a local drive. 

The default directory name is: 

‘C:\PsyQ_Win\’ 

and it isrecommendedthdii you follow this convention. Set-up also installs several 
Files in the Windows System directory and adds two keys to the Registry. 

These keys are: 

[HKEY_LOCAL_MACHINE\SOFTWARE\SN Systems] (hardware settings) 
[HKEY_CURRENT_USER\Software\SN Systems] (configuration information) 

Set-up also registers the Eile typespsy (Project), .pqx (plug-in) and.cpe and adds 
some programs to the Start menu. 


IMPORTANT: Do not install the program on a server and execute it across a 

network. Eor un-installation advice, please contact SN Systems. 
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Obtaining Releases And Patches 


Releases and patches are available directly from SN Systems’ BBS and ftp sites. In 
order to access these sites you will need an account with the necessary permissions. 

To apply for an account telephone SN Systems or contact them via 
Support@snsys.com. 


Note: Members of the Windows-Users mailing list will be notified of releases and 
patches as they become available. 


Determining The Latest Reieases And Patches 

This is achieved via any of the following methods: 

• ContactJohn@snsys.com 

• Look in one of the File sites for the latest Files and information 

• See http://www.snsys.com 

Maiiing Lists 

SN Systems maintain a number of mailing lists for different purposes. For further 
information see http://www.snsys.com. 

Addresses for SN Systems’ ftp, web and BBS sites 

• ftp://bbs.snsys.com 

• http://www.snsys.com 

• BBS - +44 (0)117 9299 796 and +44 (0)117 9299 798 
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Beta Test Scheme 

SN Systems maintain a separate scheme for beta testing new versions of the 
Debugger. 

The benefits of this are as follows: 

• You will receive new versions of the Debugger before any other user 

• You will have a prioritorised chance to supply feedback to the Debugger’s authors 

If you are a member of this scheme, you don’t need to install release versions of the 
Debugger. 

For more information, contact John@snsys.com. 
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Installing A Full Release 


A Full Release File contains an archive of several Files and a Set-up program that can 
be used to install the Debugger automatically. 


To install the release: 

1. Obtain the latest full release from SN Systems. 

2. Read Readme.txt which contains last-minute installation instructions. 

3. If the release is on a floppy, launcBetup.exe straight-away. If however, the 
release is in a zip File, you must unzip the File into a temporary directory and 
then launch Setup from that temporary directory. 

4. If this is the first full installation of the Debugger, confirm the displayed license 
conditions. 

5. Specify or confirm the directory in which you wish to install the Debugger. 

6. The Files will be installed and the Registry will be updated. 

7. Depending on the type of installation, specify the settings for the DEX Board or 
SCSI Card. (See Configuring Your Dex Board/SCSI Cardbelow). 

8. Once the dialogue has been completed the installation is complete. 


Note: This method can be used for the first installation of the Debugger and also for 
subsequent upgrades if you do not wish to use Maintenance Patches. See 

Upgrading Your Systembelow. 
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Upgrading Your System 


From time to time, SN Systems will provide updates to the Debugger that introduce 
bug fixes and new features. For your convenience, updates are supplied as full 
installationsand as maintenance patches. 

A Maintenance Patch contains only the difference between Files so it is much smaller. 
This makes it quicker to download and apply. However, patches can only be applied 
over certain previous versions. 


To apply a Maintenance Patch: 

1 . Determine your current release by reading thAbout box for the Debugger. 

2. Obtain the Maintenance Patch from SN Systems. Instructions will be provided so 
you can determine which patch must be applied. 

3. Apply the patch according to the instructions. 
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Confijpirinil Your SCSI Card 


If you are installing a Full Release for a SCSI Target, you must specify the settings 
for the SCSI Card. 


► 


Enter appropriate values to the dialogue box displayed duriil^e Set-up program 



SCSI Card Settings Dialogue Box 

1. Specify aPort Address and IRQ value by clicking on the down arrows and 
selecting as appropriate. 

2. Click I 

The installation is now complete. 


IMPORTANT : Port Address and IRQ values must be correct for the Debugger to 
work. If they are incorrect or another device is configured to use 
similar settings, the programs will not work. 


Note: The IRQ value can be set toO to run without interrupts. This will help with 
trouble shooting and will only impair the performance of the system if you 
make a lot of use of file or message serving. 
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Testing The Installation 


Once the Debugger has been installed, you should test the installation as follows: 

1. Ensure that the Nintendo 64 is switched off and that the Target Adapter and 
game cartridge are connected to it. The power should be on for the Adapter and 
the bottom LED should be flashinglowly, indicating that thebios has not yet 
been loaded.. 

2. Run the Eile Server by selecting the Debugger Eile Server from the Start menu. 

3. This will attempt to connect to the Nintendo 64 console. If the connection is 
successful the Eile Server will download the bios; the bottom LED will go out 
and the following text will be output from the Eile Server: 

Psy-Q File and Message Server, Copyright 1996, 1997, SN Systems Ltd 
Version 2.0 (January 1997) 

Release 10, Patch Level 3 

Target Found: Bus ID = 0, SCSI ID = 0 

New Downloader - Reading profile information... 

Profile read for Nintendo 64 (no hios) 

OK 

Rebooting the Nintendo 64 (no hios)... 

Getting the target’s ID... 

ID is N64-NO-BIOS PLEASE LOAD 

hiosl... 

sleep .5 sec... 

hios2... 

sleep .5 sec... 

New Downloader - Reading profile information... 

Profile read for Nintendo 64 

If this has occurred communication will have been established between the PC 
and the Nintendo 64. 

4. Now you are ready to download a test cartridge image into the cartridge RAM. 
Proceed as follows: 

5. From the File Server select th^ools menu. 

6. Select the Uploader option. 

7. Click the Download radio button and change thDownload Addressto 

OxBOOOOOOO . 
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8. ClickB^rowse and select the filetest .bin from thepsyq-win\examples\n64 
directory. 

9. Click OK. 

The downloaded image is now in the cartridge RAM. 

10. Switch on the Nintendo 64. The system will boot the image and stop at a 
breakpoint at the start of the program. 

11. Run the Debugger from the Start menu. 

12. You are now ready to begin debugging. 
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Documentation 

If you experience problems during installation, the following documents provide 
useful information: 

• README.HTM 

• README.RTF 

• README.N64 
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Using The Check System Diagnostic Tool 


The Check System Diagnostic Tool is a Plug-In which is used to check for faults in 
the Debugger installation or hardware and if any are found and a compatible Email 
program is in use, to automatically generate a report of them to SN Systems Support. 


There are two ways to access the Diagnostic Tool: 

1 . Either, first select the Debugger group from the Program menu and then the 

Check System for Errorsoption. 

Alternatively, selecSystem Diagnostic Tool from the mainTools menu. 
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Via the displayed Diagnostic Tool Dialog you can check the following areas: 


Plug-Ins - That the required Plug-Ins are installed and that files are 

actually present for registered Plug-Ins. 

Windows System - That the required DLLs are present and are the correct 

size and version. 

Registry - That the registry settings are correct. 

Target Connection- That the Target is communicating with the PC. 

System Files - That a list of the installed Psy-Win files has been printed. 


The results of any previous diagnostic checks will be shown for each group. 

2. By default, the diagnostic process will includdl the above groups. To exclude a 
particular check or checks from the run, de-selednclude in Diagnostic Check 
for each relevant group. 


3. Click the. 


Run Diagnostic Check 


button. 


If any errors are detected you will be prompted to mail SN Systems support. 


4. Provided that you have a MAPI compatible Email program and it is currently 


running, click r ; -I and your email window will appear. Each attached 

file to be sent to SN Systems support contains error information for one of the 
checks. 


Note: Click the required | button on the Diagnostic Tool Dialog to 

examine these details yourself. 

6. Enter a description of the error(s) and send the mail as normal. 

7. Click the appropriate— button to repeat any particular check. 


8. If no errors are detected but you still suspect problems, click the 
^ Emaii SN Systems Support j], ... .u j- u i 


I ^ — 1 button to re-run the diagnostic checks and manually 

access the email program. Send a message as required. 
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Launching The Debugger 


There are several ways of launching the Debugger under Windows 95. 


A simple way is as follows 

1. Select the Start menu from Windows 95. 

2. Choose the Programs option from the list displayed. 

3. Select thePsy-Q folder from the list of programs. 

4. Select Debugger from the folder. 

You can also launch the Debugger from the desktop or folders or through Explorer 
in Windows 95. 

When you close the Debugger, it will remember the current working directory and 
restore this when it is re-opened. 

The Debugger will also remember the current state of the flashing caret when ids 
loaded. If you turn the flashing off, it will remain off until you close the Debugger, 
when it will be restored. If you then re-open the Debugger, the caret flashing will be 
stopped again. 


Note: Switching away from the Debugger will not re-start the caret flashing. 


With the drag and drop facility you can drop a Debugger Project File (extension 
.PSY) onto the icon of the Debugger and the selected Project is launched. 

Alternatively, as file type .PSY has been registered with the Windows 95 shell, you 
can right-click on a Project File, selecDebug from the menu and the Debugger will 
be launched with the selected Project. 


Note: While the Debugger is still running, you can opennaew Project by following 
the procedure described in the previous paragraph. 


When you launch the Debugger it scans for recognised Units and if none are found a 
dialogue box prompts you to eitheiRepoll or Quit. If Repoll does not work you are 
advised to start troubleshooting. 
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The File Server 


The primary function of the File Server is to provide the PC Open and PC Read 
functions for your program. 

When the File Server is running, the icon and name of the application appear on the 
Task bar of Windows 95. 

You can view the messages appended into the message window of the File Server 
during debugging by clicking on this icon. 



File Server Message Window 

If you wish the message window to be permanently displayed on top of other 
windows, select Always oiiTop from the View menu. 

When the Debugger or File server experiences a communication error, the screens 
will go blank. PressCtrl + U to re-attempt the connection. 
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File Server Menu Commands 

In addition, the following options are available from the File Ser^ffiommand menu: 

• Run Project - Not currently in use 

• Debug Project - Not currently in use.. 

• Download CPE File to the Target. 

• Run CPE uns the Target after the CPE File has been downloaded. 

• Ping etermines the current status of the Target 

• Halt provides the option to stop the Target if it is running. 

• Start causes the Target to start running. 

• Clear Window removes any File Server messages. 

• Reboot Target reboots the Target. 

• Reset Target will attempt a hardware reset if supported by the Target. 

• File Serving [etermines whether file and message serving are available. 

• Telnet Server determines whether the Telnet Server is accessible. 


Note: Resetting the Target while the Debugger is running may cause unpredictable 
results. 


Note: The Reset option is also available from the System menu of the File server. 


Note: When you close the File Server, it will remember the current working 
directory and restore this when it is re-opened. 
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Connecting The Target and Unit 


The Debugger automatically checks your system when you launch it, identifies any 
Targets that are connected and according to whether you are running a single or 
multi-Unit system, automatically connects to the relevant Unit(s). 

The Unit toolbarappears at the far right of the Main Menu bar. The last icon in the 
toolbar has a pictogram of the Target known as the Unit button. 

There will be a Unit toolbar and unique button for each Unit identified. Click on the 
button to display the Unit menu. This menu allows you to download and load (as 
relevant) foreign CPE and foreign Symbol Files and download non-foreign CPE and 
Binary Files. 

The Unit button menu options are: 

• Download CPE 

• Download Binary 

• Load Symbols 

Each toolbar contains a set of debugging icons which represent: 

• Starting programs 

• Stopping a program running 

• Stepping into a subroutine 

• Stepping over a subroutine 

• Stepping out of a subroutine 


Note: Note that these actions operate only in respect of the relevant Unit; therefore, 
where a multi-Unit system is in use they will not necessarily operate in respect 
of the Active View. 


Note: The File Server window displays any output from the Target while it is 
running. 
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Plug-In Components 


The Debugger provides two types of Plug-In components; these provide additional 
functionality or extend the Debugger in some way and are installed separately. They 
are categorised as follows: 

• Tool Based Plug-Ins 

• Pane Based Plug-Ins 


To install or remove a Plug-In component: 

1 . Select the Plug-In Manager from thffools menu. 



Plug-In Manager Installation/Removal Mode 

2. This dialog allows you to install or remove all the Plug-Ins currently available on 
your machine. If you wish to restrict the display to Tool-based or Pane-based 
versions only, select the relevant group from thPlug-In Category pull-down 
menu. 


3. 


Select as required and clicl 


Install... 


or 


Remove 


as necessary. 


You will now be able to access the installed Plug-Ins. 
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Tool Based Plug-Ins 

The following facilities are available: 

• Plug-In Manager 

• Check System Diagnostics 

• Upload/Download Memory 

• Disassemble Memory 

• View and editBreakpoints 


To access a Tools-based Plug-In component: 

From the main Tools menu, select the required option. 

A relevant dialog box will be provided for the entry and inspection of information. 


Pane Based Plug-Ins 

The following facilities are available: 

• Plug-In Manager 

• Breakpoint Manager 

• Call-Stack Display 

To access a Pane based Plug-In: 

1. Right-click in a relevant Pane. 

2. Select ChangePane. 

3. Select Other or Ctrl + Shift + O. 

4. The Plug-In Manager will display the currently available Pane Plug-Ins. 
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Plug-In Manager When Switching Between Panes 

5 . Select as required and click 

Information from the selected option will be displayed in the Pane. 

Note: The functionality of the Breakpoint Manager Pane is the same as for the 
Tool based Breakpoint Dialog. 


6. To switch to another Pane based Plug-In, repeat stepl to 5. 
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Using The Disassemble Memory Dialog 


The Disassemble Memory Dialog is a Tools based Plug-In which is used to produce 
a machine code disassembly of a specified area of memory, similar to that which 
appears in the Disassembly Pane. 

The area to be disassembled can be specified as an address range, as a number of 
bytes or as a number of instructions. The output can be copied to a file on your PC 
or it can be sent to the Windows clipboard to be pasted directly into another 
Windows program. 


To access the Disassemble Memory Dialog: 

1. From the mainTools menu select the Disassemble Memory option. 



2. Specify where the disassembled memory is to be output. 

Where it is to be output to a file the name and path can be explicitly entered or 
click and select as required. 

Alternatively, to save to the Windows clipboard check tlSave to Clipboard 
box. 

3. Specify the Start Address, i.e. the address on the Target’s memory from where to 
start the disassembly. This value is always in hexadecimal. Click on the adjacent 

button to call up the Expression Manager; from here you can specify an 
expression to be used as the start address. 
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4. Specify aStop Value. If the Stop With entry is an address, the Stop Value must 
be in hexadecimal If the entry to Stop With is a number of bytes or instructions 
however, the Stop Value must be iidecimaL 


When the Stop Value is specified as aaddress, the Expression Manager is 
available via th e button. 


5. 


Click 


OK 


when the values have been specified. 
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Using The Upload/Download Memory Tool 


The Upload/Download Memory Dialog is a Tools based Plug-In which allows you 
to: 


• Upload a portion of memory from the target machine to a file on the host 
machine 


or 


• Download a portion of memory from the host machine to the target machine 

It is then possible to save and restore the state that a machine’s memory was in prior 
to an exception occurring. 


To access the Uploader/Download Memory Dialog: 

1. From the mainTools menu, select the Upload/Download Memory option. 

2. Select the required mode from the relevanUpload/Download Memoryradio 
buttons. 



Upload/Download Dialog With Upload Image Selected. 

Only one option can be selected at a time and the default model^load. 

When Upload Image is selected you must specify tlErom and To positions of 
the required imageor check the Length box and only specify aFrom position if 
you wish this to represent the length of a block of memory. 
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When Download Image is selected you only need to specify t^ address as 
the memory to be downloaded is calculated from the size of the file from which 
memory is being downloaded. 


Note: Clicking the button will invoke the Expression Manager via which 
you can search for and specify particular addresses. 


3. Enter a name to the Binary Eile box; this can be the complete name and path or 
click and select as appropriate. 


4. If you are uploading memory you will be asked to supply a filename to which the 
portion of memory should be saved. If you are downloading memory, you must 
specify the name of the file from which the memory will be taken. 


Note: If you click on the downward arrow adjacent to each edit box, a list of 

previously used addresses or files (as relevant) will be displayed. The most 
recently used items will appear at the top of the list. 


5. Click 


OK 


and an attempt is made to upload or download the memory. 
Errors resulting from this action will be displayed in the Eile Server window. 

I 

Cancel 


Click. 


to exit the dialog without uploading or downloading memory. 
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Projects 


A Project is a combination of the elements and settings associated with a specific 
development project. 

It consists of any or all of the following: 

• Units to be debugged 

• Screen layout 

• CPE Files 

• Symbol Files 

• Binary Files 

• Breakpoints 

• Other settings and preferences. 

This set of information is used by the Debugger to track the debugging process. 
When you save a Project this includes all the Views, colour schemes and breakpoints 
already specified for it. These settings are reinstated when the Project is next 
opened. 


Setting Up And Managing Projects 

To create a new Project youcan either: 

1. Open the default Project by selectin^ew from the Project menu. 

2. Save and name the Project, 
or 

1. As 1) above. 

2. Select files for the Project and add them to the file list. 

3 . Set file properties for executable files. 

4 . Save and name the Project 

5 . Re-open the Project with the files in the file list. 
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Selecting Files For Your Project 


► 


The Debugger uses files that are output from the build process. Three types of file 
may be included in the Project; these are: 

• CPE Executable Eiles 

• Symbol Eiles 

• Binary Eiles 


Adding Files To The List Of Project Files 

This is achieved as follows 


1. Select the Project menu from the Menu bar. 

2. Choose Files from the menu; the Files dialog appears. 

3. Click — I to insert them into your file list. 

4. Select CPE, Binary or Symbol Files from th^'iles of Type’ drop-down list. 


5. 

6 . 


Eocate the file and clicl 


OK 


When you add a file to the file list a relevant dialog box requests you to set the 
file properties. For CPE and Binary Files these will determine the downloading 
of files to the Target. Additionally, for Binary and Symbol Files, they determine 
the Unit to which they will be loaded. See thdJnderstanding File Properties’ 
sections below. 


Note: It is not necessary to specify the Unit to which a CPE File should be loaded 
as this information is held within the file itself. 


7. 

8 . 


Repeat the operation until all the files you require appear in the list. To remove a 
file from the list, highlight it and di r | 


Click 


Close 


when you have added all the files you require. 


The CPE and Binary Files will be downloaded in the order shown in the file list. 
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Note: As file type .CPE has been registered with the Windows 95 shell, you can 
run a program directly from the shell by double-clicking on the relevant 
CPE Eile. Alternatively, if you wish to download the file to the Target 
without running it, right-click the relevant file and seleBownload from 
the menu. 


Note: When you add Binary and Symbol Eiles to a Project they are not loaded 
until the Project is saved and re-opened. 


Changing The Order Of Files In The File List 


If you have multiple CPE and Binary Eiles within your Project, the order in which 
they are loaded during debugging is determined by the position you placed them in 
the Pile list. 


To change the file sequence 

1. Select the Project menu from the Menu bar. 

2. Choose Files from the menu. 

3. Highlight a file. 

4. Use E’omote I Qj- — emote | jq position of the file in the list. 

Repeat the process until the files are in the required order. 

Note: This option is only useful if you have multiple CPE and Binary Files in your 
Project and the load order is important. 
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Specifying CPE File Properties 


► 


When you select a CPE File to include in your Project, a dialogue box requests that 
you set the properties for this file. 

These properties allow you to control the downloading of files to the Target. The 
options are: 

• Download when Project starts- This causes the CPE File to be downloaded 
when the Project is opened or reopened. 

• Run after CPE has been downloaded- This causes the Unit to start running the 
code after downloading the file. 

You may select either or both of these properties for any CPE File in the Project. 

If you do not set the properties of at least one CPE File, the Debugger will not 
download any files to the Target when the Project is opened. 


To change CPE File properties: 


1 . 

2 . 

3 . 

4 . 

5 . 

6 . 


Select the Project menu from the Menu bar. 
Choose Files from the menu. 

Select the CPE File to change. 

Click 

Use the check boxes to apply the properties. 


Click 


Close 
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Specifying Symbol File Properties 


When you select a Symbol File to include in your Project, a dialogue box requests 
that you confirm or specify the Unit to which the file should be loaded. 


► 


To change Symbol File properties 

1. If the required Unit is not already displayed, click the down arrow until it 
appears. 

2. Highlight the required Unit. 

3. Click 

4. Click 


OK 


Close 
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Specifying Binary File Properties 


When you select a Binary File to include in your Project, you must complete the 
following dialogue box: 



Binary File Properties Dialogue Box 

These properties allow you to control the downloading of files to the Target: 

• Download when Project starts- If this is selected the Binary File will be 
downloaded when the Project is opened or reopened. 

• Downloaded to a specified address- The files will be downloaded to the address 
specified. This should be in OX notation for hexadecimal numbers. The default 
address will be zero. 

• Specify the Unit where the File is to he loaded- Click on the down arrow to 
display further Units. 

If you do not set the first option for at least one Binary File, the File Server will not 

download any Binary Files to the Target when the Project is opened. However, all 

Binary Files in the Project will be available on the relevant Unit menu. 


To change Binary File properties 

1 . Select the Project menu from the Menu bar. 

2. Choose Files from the menu. 

3. Select the Binary File to change and plip Properties... | 

4. Select the Download when Project startsoption if required and/or enter a 
relev ant address. 

5. Confirm or specify the Unit where the File is to be loaded. 

6. Click 
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Saving Your Project 


► 


Once the files have been seleeted, the new Project must be saved and re-loaded 
before debugging can begin. 


This is aehieved as follows 


1 . Select the Project menu from the Menu bar. 

2. Choose the Save option from the menu. 

3. Give a name and path to your Projeet. 

4. File names in Windows 95 are up to 250 eharaeters long and ean eontain spaees. 
Debugger Project Files must be saved with the default File extension.PSY. 


5. Click 


Save 


Note: For a new Project you can choose the Rtore rather than theSave option. 
Restore prompts you to save the Project before reloading it. 


Note: The Save or Save As options can be used to save an existing Project. 


Re-opening A Project 


After saving a new Projeet you must re-open it before working with the files which 
have been added to the file list. 


This is achieved as follows 

1 . Select the Project menu from the Menu bar. 

2. Choose the Re-open option from the menu. 


Note: Ctrl + Ror the Re-open icon on the toolbai. 
a Project. 


can also be used to re-open 


Note: When you close the Debugger it will remember the eurrent working directory 
and restore this when it is opened. 
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Saving A Project Under A New Name 


The Save As option on the Project menu is used to save changes made to an existing 
Project, under a new name. 

The default File extension for a Debugger Project iPSY. When you save Project 
Files you must use this extension. 

To save a Project under a new name 

1. Select the Project menu from the Menu bar. 

2. Choose the SaveAs option from the menu. 

3. Give a name and path to the renamed Project. 

4. Click I I. 


Restoring A Project 


The Re^ore option on the Project menu is used to re-load a Project in the state in 
which it was last saved, abandoning any changes made since the last save. 

To restore a Project 

1. Select the Project menu from the Menu bar. 

2. Choose the Reiore option from the menu. 
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Opening An Existing Project 


When you launch the Debugger, the last Project you worked on will be loaded 
automatically. 

To open a different Project 

1 . Select the Project menu from the Menu bar. 

2. Choose the Open option from the menu. 

3. Select the Project (.PSY) you require. 

4. Click I Qpen I. 


From the Project menu select the required Project from the Project File history 
listing.. 


Note: An existing Project can also be opened via the Open Project ici, 
on the toolbar. 


found 


Note: As File type .PSY has been registered with the Windows 95 shell, you can run 
a Project by double-clicking on the relevant .PSY File within the shell. 
Alternatively, if you only wish to load the Project into the Debugger, right- 
click the relevant file and selecDebug from the menu. 
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Manually Loading Files Into A Project 


► 


► 


External Files ean be downloaded at any time; they are not saved with the Projeet. 
External CPE Files are downloaded to the Target as follows: 

1. Cliek on the Unit menu at the base of the Debugger sereen. 

2. Choose the Download CPE option from the menu. 

3. Choose the External File option. 

4. Browse and seleet the required CPE File. 


Note: You can also download a CPE File by double/clicking it within the shell. 


Symbol Files can beloadedinto the Debugger as follows: 

1. Click on the relevant Unit menu at the base of the Debugger window. 

2. Choose the Load Symbols option from the menu. 

3. Browse and select the required Symbol File. 

4. Cliek I 

Note: An error message will be displayed if you attempt to load Symbol Files with 
overlays. This facility will be supported in a later version of the software. 
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The Debugger Productivity Features 


To enable you to work faster and more efficiently when using the Debugger, the 
following two features speed up your control of the debugging runs. 

• Toolbar Icons 

• Hot Keys 


Toolbar Icons 


niFiinimiraiB 


The toolbar contains the group of icons shown above. Icons provide a quicker means 
of activating commands and setting properties. 

From left to right they represent the following actions: 


Open a Project File 

Save and then reopen the current Project 

Open a new View 

Switch to the next View 

Split the Active Pane horizontally 

Split the Active Pane vertically 

Delete the Active Pane 

Set the default colour scheme 


The Show Toobar option on the Project menu is used to toggle the menu bar on and 
off. When the option is ticked the toolbar is displayed. 


To toggle the toolbar 

1 . Select the Project menu from the Menu bar. 

2. Choose the Show Toobar / Hide Toobar option from the menu. 


Note: Every Pane type has its own, additional toolbar which is appended to the 
main toolbar when that Pane is made Active. 


Note: Double-click to customise a toolbar or us Alt+Drag to move buttons around 
the toolbar or delete them. 
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Hot Keys 


The following Hot Keys can be used instead of the Debugger menu options: 


F2 

Split Horizontal. 

F3 

Split Vertical. 

F4 

Delete current Pane. 

F5 

Toggle breakpoint on and off. 

F6 

Run to cursor. 

F7 

Step into a subroutine. 

F8 

Step over a subroutine. 

F9 

Run a program. 

F12 

Step out of a subroutine. 

Esc 

Stop a program running. 

Ctrl + A 

Add a watch to a Watch Pane. 

Ctrl + B 

Add horizontal scroll bars to Expression, Disassembb 
and Source Panes. 

Ctrl + L 

Add locals to a Watch Pane. This command adds all 
locals to the watch but when the watch goes out of 
scope it will not delete them as in a Local Pane. 

Ctrl + M 

Toggle the stepping mode between Source and 
Disassembly 

Ctrl + R 

To Re-open. 

Ctrl + Shift + D 

Change Pane to Disassembly Pane. 

Ctrl + Shift + L 

Change Pane to Local Pane. 

Ctrl + Shift + M 

Change Pane toMemory Pane. 

Ctrl + Shift + R 

Change Pane to Register Pane. 

Ctrl + Shift + S 

Change Pane to Source Pane. 

Ctrl + Shift + T 

Toggle between hexadecimal and decimal globally. 

Ctrl + T 

Change the mode of a single expression from hex to 
decimal or vice versa. 

Ctrl + Shift + W 

Change Pane to Watch Pane. 

Ctrl + Shift + number 

Assign an identifying number to each View. 

Ctrl + number 

Switch between Views. 

Shift + Arrow Keys 

Activate adjacent Pane in the specified direction. 
Where more than one, the current caret position 
determines the Pane to be made Active. 

Shift + Ctrl + FIO 

Set the width to match the size of the window in the 
Memory Pane. 

Ins 

New View or add a watch in a Watch Pane or add a 
breakpoint in the Breakpoint Manager. 

Alt + Shift + number 

Assign an identifying number to each Plug-In Pane. 

Alt + number 

Switch between Plug-In Panes. 


Note: These keys will all operate in respect of thActive Pane. 
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Views 


A View appears in the main window of the Debugger; it is used to display debugging 
information according to your requirements and to control step and trace actions 
during debugging. 

When a Project is first created it has a default Pane layout. 

Views can be split into as many Panes as you wish. These can be of the same or 
different types. 

Only one is Active at any time; it will be displayed in a different colour scheme to the 
others. 


Notes: Having created a View of different Panes you can save this as a View File 
either in, or independent of, the Project. Further information about Panes 
can be found inWorking With Panes and Selecting A Pane Type 
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Creating A View 


Within a Project you can create as many Views as required; in turn, each View can 
be split into as many Panes as you need. 


When you open a new Project, one View is displayed for each Unit connected. 
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DIS ^ 


Default View 


► 


To create a new View: 


1. Select the View menu from the Menu bar. 

2. Choose the New option from the menu. 

3. From the Choose Unit box specify the Unit for which you wish to create a new 
View. 


Note: The Choose Unit box will not appear when you are connected tosangle 
Unit. 
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You can also use the New View icon on 
use the Hot Key Insert 


the toolb; 


Q 


to create a new View or 


Alternatively, you can open a new View from the relevant Unit button, in which case 
you won’t be prompted for the required Unit. 


Note: A new View is supplied with the title ‘Default View’. Tlfdiew Name option 
in the View menu should be used to give it a title. 


Note: Views can be saved either inside or outside of Projects. 


Cycling between Views 


If you have more than one View open within a Project you can cycle between them 
as follows: 

1. Select the View menu from the Menu bar. 

2. Choose the Next View option. 

The Views are cycled around until you see the one you require. All Views appear on 
the View list regardless of the Unit for which they have been specified. 


Alternatively, the Next View icon on the toolball2 
Ctrl + TAB can be used to cycle between Views. 


, the Hot Keys Ctrl + F6 or 


Up to ten Views can each be assigned an identifying number from 0 to 9; the number 
of the assignment will appear in the title bar of the View. You can then use the 
number to quickly switch between Views. Seledftrl + Shift + numberto assign 
the number andCtrl + numberto access the View. If the destination View is 
minimised, it will be restored or maximised according to the state of the current 
View. 


Note: These assignments are preserved in Projects and in saved Views. 
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Saving Your Views 


Any number of Views can be saved within a Project. 

All open Views will automatically be saved when you save the Project and will be 
opened when the Project is re-opened. 

View Files can also be saved independently of Projects using the S^e command 
on the View menu. 

This is achieved as follows: 

1. Arrange the Panes as you require. 

2. Select the View menu from the Menu bar. 

3. Choose the SaveAs option from the menu. 

4. Give the View a name and path. 

5. Click I I. 


Note: The name you give the View File is not displayed on the View. To give a 
View a title use theView Name option on theView menu. 


Naming A View 


► 


Because you can use many Views within a Project, it is helpful to give each View an 
individual title. 


1 . 

2 . 

3. 

4. 


Select the View menu from the Menu bar. 
Choose the View Name option from the menu. 
Enter the View name in the edit box. 


Click 


OK 


. The name appears at the top of the View. 


Note: This is not the name of the File. See the note iSaving Your Views above 
for further details. 
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Changing Colour Schemes In Views 

^ To change the colours for a particular Unit 

1. Activate a View/Pane on the Unit that you wish to set colours for. 

2. Select the View menu from the Menu bar. 

3. Choose Set Default Colours... from the menu. 

The following areas may be changed for the Active Unit: 

Inaetive Pane background colour 
Inactive Pane text colour 
Active Pane background colour 
Active Pane text colour 
PC text colour 
Changed information colour 
Breakpoint background colour 
Breakpoint text colour 

4. Click on the box representing the area you wish to amend. 

A standard Windows dialogue box allows you to choose from a range of standard 
or customised colours. 



Set Default Colours Dialogue Box 
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5. Select the required colour(s). 


The selected colour scheme will be displayed for all visible Views. 

Cancel 


6. Select 


OK 


to retain the revised colours oi_ 


to 


revert to the original scheme. 


Unit colours can also be amended by clicking on the Set Colour ic 
toolbar. 



on the 
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Working With Panes 


When a Project is first set up, the default View contains a default Pane layout for 
each Unit connected. However, this View can be split into as many Panes as you 
wish. These can be of the same or different types. Only one of the Panes is Active; 
it will be displayed in a different colour scheme to the others. 


A Pane can be made Active via any of thfellowing methods; 

• Clicking on it 

• Changing the ActiveView and the first Pane created for that View will become 
Active 

• Using Shift and the appropriatearrow key to Activate the Pane in the specified 
direction 

• Clicking the right mouse button on the required Pane and selecting from the 
displayed menu 


Splitting Panes 


► 


A View can be divided into as many Panes as you wish. Click on the one you wish to 
split to make it Active, then 


1. Select the View menu from the Menu bar. 

2. Choose either SplitVertical or SplitHorizontal from the menu. 

The Active Pane is split in half, either vertically or horizontally, depending on your 
choice. 


You can also split a Pane horizontally or vertically via the icons on the toolbar 


mm 


or by using the hot keysF2 to split horizontally oiF3 to split vertically. 


Note: When you split a Pane the two halves will both be of the same type as the 
original. The font for the new Pane will also match that of the original. 
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Changmg Pane Sizes 


To change the size of Panes: 

Drag the splitter bar between the Panes with the mouse. 

The size and position of the Panes is saved when you save the View or the Project. 


Note: Splitter bars only control the areas between the Panes. If you wish to change 
the size of the Debugger window you have to use the borders of the window 
itself. 


Deleting A Pane 


► 


The Delete Pane option on the View menu is used to delete a Pane within a View, as 
follows: 


1 . Click on the required Pane to make it Aetive. 

2. Select the View menu from the Menu bar. 

3. Choose Delete Pane from the menu. 


Alternatively, the Delete Pane icon on the toolb; 
to delete the Aetive Pane. 


m 


or the hot keyF4 ean be used 


© SN Systems Ltd 




Page 10-46 


Windows 95 Debugger 


Nintendo 64 


Changing Fonts In Panes 

^ If required, the SetFont eommand ean be used to ehange the display of text within a 

Pane, as follows 

1. Make the required Pane Aetive. 

2. Select the View menu from the menu bar. 

3. Choose SetFont from the menu. 

A standard Windows dialogue box allows you to select from the available fonts. 


Note: When you split a Pane, the new Pane will be displayed in the same font as the 
original one. 


IMPORTANT: You will only be able to use non proportional fonts, e.g. Courier, 
New Courier, Fixed Sys, Terminal.. 


See Also: 

Changing Colour Schemes In Views 
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Scrolling Within A Pane 


Many Panes are unable to display the full set of information that is available to the 
Debugger in the small screen area shown. Therefore, the Debugger puts scroll bars 
onto Panes where there is more information than can be displayed on that part of the 
screen. 

To see this additional information drag the thumb within the scroll bar or click on the 
arrows at either end of the scroll bar. 


Note: Horizontal scroll bars are not automatically included in Expression, 
Disassembly or Source Panes but they can be added vGtrl + B. 


You can also scroll to the region you want by clicking on the required Pane to make 
it Active and then clicking and holding the left mouse button before dragging it to the 
top or bottom of the Pane. 


See Also: 

Changing Pane Sizes 
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Selecting A Pane Type 


There are six types of Pane and you may display any number and combination. 

A menu that allows you to change Pane properties is accessed via the Pane menu on 
the Menu bar or by right clicking the mouse on a relevant Pane. These menus are 
unique to the type of Pane that is Active but all the menus have the optifihange 
Pane that allows you to switch between the different types. 

Additionally, icons representing each type of Pane appeadjacent to the main 
toolbar. 


Registers Pane - Displays the registers of the relevant CPU 

Memory Pane - Displays areas of memory within the Target 

Source Pane - Displays Source Files associated with program that CPU is running 

Disassembly Pane- Displays the code that the CPU is running 

Watch Pane - Displays ‘watches’ or expressions 

Local Pane - Displays local variables 

Click on the relevant icon to change the Active Pane. 


Note: You can also use the Hot Keys to switch between Pane types. 
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Icons representing menu options for the selected Pane are dynamically appended to 
the far right of the main tool bar. For example, if Disassembly Pane is Active, 
Disassembly Panmptions will be displayed. 


Further details about the options for each type of Pane can be found below. 


Memory Pane 


There are three areas displayed on the Memory Pane: to the left is the memory 
address; in the middle is the value at the displayed memory address; and to the right 
an optional ASCII display of the values which can be toggled on or off. 


F Pey-Q Debugger for Windows - [Memory] 


C Project View Debug Memory \Mndow Help 

pigaimiSTE] HSIT 


jOOOOOOO 

lOOOOOlO 

10000020 

10000030 

10000040 

10000050 

10000060 

10000070 




□□ 




I Mil Hill :ii» i 

■ TTi MMirin I 

■ "wn WTiTf'rn i 

■ I 


C0000003 275A0C50 03400008 OOOOOOCO II 
COOOOOOO 00000000 OOOOOOOO OOOOOOCO II 
COOOOOOO 00000000 OOOOOOOO OOOOOOCO II 
COOOOOOO 00000000 OOOOOOOO OOOOOOCO II 
CCIAIFAO 375A0440 03400008 OOOOOOCO I 
COOOOOOO 00000000 OOOOOOOO OOOOOOCO II 
COOOOOOO 00000000 OOOOOOFF OOOOOOCO II 
A000E4F8 00000000 OOOOOOOO OOOOOOCO 0 a 


“ I ^^1 double word a: 00000050 


I IPIZ' I l?l I II I 


K@IZ7I I? 


16 



Memory Pane Display 


You can goto an area of memory by typing the required address over the memory 
address or by selectin^oto from the Pane menu and entering a known address or 
label name to the dialogue box displayed. 


See Also: 

Moving To A Known Address Or Label 


Use the scroll bars or th^oto functions described above to move around the display. 
The default setting for the Pane is in bytes with the ASCII display set. 
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Change this default by selecting the Pane menu and choosing from the options: 

• Bytes 

• Words (bytes x 2) 

• Double words (bytes x 4) 

• ASCII (Toggle ASCII display on and off) 

• Set Width (Changes the number of bytes displayed on a line) 



Alternatively, clicking on these icons will activate the 


options listed above. 


You can overtype the hexadecimal or ASCII displays to alter the content of the 
memory. A change to the hexadecimal display will be reflected in the ASCII display 
and visa versa. 


When you move the mouse pointer over the values, the Status line displays the 
Memory Address and one of the following Memory Types: 

• RAM 

• ROM 

• Invalid. 


Invalid memory is displayed as question marks instead of hexadecimal values and full 
stops instead of ASCII. 

The Set Width icon can be used to change the width of the display; click on the icon 
and type in the number of bytes to be shown on each line. 

Shift + Ctrl + FIO can be used to set the width of the Pane to match the 
size of the window. 


The Active Pane can be made Memory Pane via any one of the following 
methods: 

Clicking on the Memory Pane icon on the toolh :^^ 

Using the Pane Type option from the Pane Menu 
Using the Hot KeyCtrl+Shift+M 
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Registers Pane 


The Registers Pane shows the registers of the central processing Unit. These can be 
overtyped if required. 

If the CPU has a Status Register, you can overwrite the individual bits by typiftgr 
‘R’ to reset the bit orl or ‘S’ to set it. 

The display also shows the disassembled instruction at the Program Counter (PC) 
and the address of the instruction which will be executed next. 

It also shows the current status and (if relevant) exception of the CPU on the bottom 
line of the Pane. 


r PsV'Q Debugger for Windows - [Register] 


Project View Debug Register Window Help 


^2 



mmm 


zH 

= 

00000000 

to = 

00007030 

sO = 

00000000 

t8 

= 00000001 

hi = OOOOOOL 

Bt 

= 

0000002C 

tl = 

00000010 

si = 

oooooooo 

t9 

= FFFFFFFF 

lo = ooooooi: 

vO 

= 

00000001 

t2 = 

00007030 

s2 = 

00000000 

kO 

= 020A8380 


vl 

= 

00000001 

t3 = 

BFA1B330 

s3 = 

oooooooo 

kl 

= BF800000 

SR = 000004L 

sO 

= 

000086BC 

t4 = 

00000004 

s4 = 

oooooooo 

gp 

= A000E4F8 



b1 

= 

BFA20E57 

t5 = 

00008690 

s5 = 

oooooooo 

sp 

= A000B348 

Ca = 0000002 

3 2 

= 

00000002 

t6 = 

00000000 

s6 = 

oooooooo 

f p 

= 1FA002EC 


3 3 

= 

000086BC 

t7 = 

00000001 

s7 = 

oooooooo 

ra 

= BFA158F8 


PC 

= 

80705708 

lui 

vO, $8070 





D topped 









I Register 


Registers Pane Display 


When you click the right hand mouse button over a Registers Pane or select the Pane 
menu on the menu bar, you will see thChange Pane Type or Pane Operations 
options. Note that these are the only menu options for this type of Pane. 


Note: If the current context stack level inot 0, the stack level (number) will appear 
in the Registers Pane as a visual warning. 


See Also: 

Using The Call Stack Display 


The Active Pane can be made Registers Pane via any of the following methods: 


Clicking on the Registers Pane icon on the toolbi 



Using the Pane Type option from the Pane menu 


Using the Hot KeyCtrl+Shift+R 
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Disassembly Pane 


The Disassembly Pane shows the disassembled code from an area of memory. 


Four columns are displayed; the first shows the address or label; the second displays 
the values at that location in hexadecimal; the disassembled op code is shown in the 
third column and the fourth contains the op code parameters. 



Disassembly Pane Display 

When the cursor is positioned on a particular label on the Disassembly Pane, the 
relevant label name and value will be displayed on the Status line. 

The Program Counter (PC) is shown on the screen preceded by the marker ‘>‘. 

When you click the right hand mouse button over a Disassembly Pane or select from 
the Pane menu on the menu bar you see the following options: 

• Copy to copy the address that the specified line represents, into the clipboard 

• Paste to paste the specified address 

• Properties - Follow PC to anchor the Pane to the Program Counter 

• Properties - Respond to Goto Breakpointto display breakpoints in all relevant 
Panes when you double-click a breakpoint 

• Properties - Centre on PCto make the Registry global setting an individual 
property of the Disassembly Pane 

• Goto to put the cursor at a known address or label name 

• Set PC to set the PC to where the cursor is 

• Toggle breakpointto set and remove breakpoints 

• Edit breakpointto disable a breakpoint or make it conditional 

• Run to cursorto run the Unit to the cursor position. 
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These options can also be activated by: 


Using the appropriate Hot Keys 


Clicking on thesel 




LL= 


icons 


Note: Ctrl + B can be used to add horizontal scroll bars to the Disassembly Pane. 


The Active Pane can become Disassembly Pane via any one of the following 
methods: 


Clicking on the Disassembly Pane icon on the toolbl = 
Using the Pane Type option from the Pane menu 
Using the Hot KeyCtrl+Shift+D 


See Also: 

Anchoring Panes To The PC 
Moving To A Known Address Or Label 
Setting Breakpoints 

Editing Breakpoints 
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Source Pane 


A Source Pane displays one of the Source Files included in your Project. 



Source Pane Display 

When you click the right hand mouse button over a Source Pane or select from the 
Pane menu on the Menu bar you see the following options: 


• Copy to copy the address that the specified line represents, into the clipboard 

• Paste to paste the specified address 

• Properties - Follow PC to anchor the Pane to the Program Counter 

• Properties - Respond to Goto Breakpointto display breakpoints in all relevant 
Panes when you double-click a breakpoint 

• Properties - Centre on PCto make the Registry global setting an individual 
property of the Disassembly Pane 

• Goto PC (space) 

• Goto to put the cursor at a known address or label name 

• Source Files to swap between the Source Files in the Project 

• Toggle breakpointto set and remove breakpoints 

• Edit breakpointto disable a breakpoint or make it conditional 

• Run to cursorto run the Unit to the cursor position. 


Note: If the Program Counter (PC) is at a line displayed on the Pane it will be 

preceded by the PC point line marker ‘>‘ and the line will be displayed in a 
different colour. 


Note: If a breakpoint exists within the Pane it will display in a contrasting colour. 
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The options listed above can also be accessed: 






By using the appropriate Hot Keys 


By clicking on thes 





III 


icons 


Note: If the display is not set to follow the Program Counter (PC), the file displayed 
may not be the one executing at the PC. 


Note: Ctrl + B can be used to add horizontal scroll bars to the Source Pane. 


The Active Pane can be made Source Pane via any one of the following methods: 


Clicking on the Source Pane icon on the toolba_^ 
Using the Pane Type option from the Pane menu 
Using the Hot KeyCtrl+Shift+S 


See Also: 

Anchoring Panes To The PC 
Moving To A Known Address Or Label 
Setting Breakpoints 

Editing Breakpoints 


Changing Source Files In The Source Pane 

By default, the Source Pane displays the Source File which contains the PC or is 
blank if the PC is out of range of your source. 

Any of the Project Source Files can be examined in this Pane by using the Source 
Files option from the Source Pane menu, as follows: 

1 . Select the Source Pane menu from the Menu bar. 

2. Choose the Source Files option from the menu. 

3. Select a Source File from the list displayed. 

4. Click I 
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Navigating Source Fiies In The Source Pane 


Each Source Pane stores a history list of the Source Files which have been viewed in 
the Pane. The following keys are used to navigate this list: 


Ctrl + J 

To go backwards. 

Ctrl + K 

To go forwards. 

Ctrl + Shift + J 

Shows the previous Source File in the list but deletes the 
current Source File from the forward list. 


The history list is stored with the Pane in the View or Project. If you insert a new 
module into your Project (as opposed to adding one at the end), the history list may 
be transposed when you next load the Source Pane. 
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Local Pane 


The Local Pane is used to display all variables in the current local scope when you 
are debugging in C. 

As you step and trace, the contents of this Pane will change to display the variables in 
the new scope. 


You can expand or collapse variables and traverse array indices. 



Local Pane Display 

Variables can be viewed in hexadecimal or decimal modes by right-clicking within the 
Pane and ‘toggling’ between Hexadecimal/Decimal (on the displayed menu) as 
required. A tick will appear alongside Hexadecimal when this mode is selected. 


Note: Ctrl + Shift + T will also toggle thonode between hexadecimal and decimal 
and Ctrl + T will toggle the mode for asingle expression. 


Any Local variable that evaluates to a ‘C’, 1-type expression, can be assigned a new 
value. 

When you select the Local Pane menu or click the right hand mouse button over a 
Local Pane you see the following menu: 

• Expand/Collapse- when the cursor is over a pointer, a structure or an array 

• Increase Index- when the cursor is over an array element 

• Decrease Index- when the cursor is over an array element. 
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These options can also be activated by: 


• Using the appropriate Hot Keys 


Clicking on these icons 


Note: Use of the Local Pane is restricted to debugging in C. 


The Active Pane can be made i^ocal Pane via any of the following methods: 

Clicking on the Local Pane icon on the toolba m 
Using the Pane Type option from the Pane menu 
Using the Hot KeyCtrl+Shift+L 


See Also: 

Using The Call Stack Display 
Watch Pane 

Expanding Or Collapsing A Variable 
Traversing An Index 
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Watch Pane 


The Watch Pane is used to evaluate and browse C type expressions. 



Watch Pane Display 


When you select the Watch Pane menu or click the right hand mouse button over a 
Watch Pane, the following menu is displayed: 


• Add Watch 

• Edit Watch 

• Delete Watch 

• Clear All Watches 

• Expand/Collapse- to view/hide the components of a structure or an array 

• Increase Index- to view higher indexed values within an array 

• Decrease Index- to view lower indexed values within an array 

• Add Locals - to add all local variables 

Note: The Add Locals command will add all locals to the watch but unlike the Local 
Pane, when the watch goes out of scope the local variables will not be deleted. 

These options can also be activated by the following methods: 

• Using the appropriate Hot Keys 

• Clicking on the appropriate icons 

Structures, pointers and arrays can be opened in a Watch Pane. 
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• If you open astructure the members of that structure are displayed. 

• If you open apointer it is dereferenced. 

• If you open anarray the first element of the array is displayed. 

The contents of the Watch Pane are saved within the View when the Project is saved. 

Variables can be viewed in hexadecimal or decimal modes by right-clicking within the 
Pane and ‘toggling’ between Hexadecimal/Decimal (on the displayed menu) as 
required. A tick will appear alongside Hexadecimal when this mode is selected. 


Note: Ctrl + Shift + T will also toggle thanode between hexadecimal and decimal 
and Ctrl + T will toggle the mode for asingle expression. 


Any Watch variable that evaluates to a ‘C’, 1-type expression can be assigned a new 
value. 


Note: The options Expand/Collapse and Increase Index ‘-i-’ and Decrease Index 
are only available for arrays, pointers and structures. 


See Also: 

Using The Call Stack Display 
Hot Keys 

Assigning Variables 

Expanding Or Collapsing AVariable 


n 


The Active Pane can be made Watch Pane via any one of the following methods: 

Clicking on the Watch Pane icon on the toolb; 

Using the Pane Type option from the Pane menu 
Using the Hot KeyCtrl+Shift+W 
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C Type Expressions In Watch Pane 

The following ‘C’ type expressions, shown in order of precedence, may be used to 
evaluate expressions within the Watch View of a Project: 


[] 

array subscript 

-> 

record lookup 


unary prefix 

*/% 

multiplicative 

+ - 

additive 

« » 

bitwise shifting 

<> <= >= 

comparatives 

== != 

equalities 

& 

bitwise and 

A 

bitwise xor 

1 

bitwise or 


Note: As in C, parenthesis can be used to override precedence. 
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Assigning Variabies 

Any variable that evaluates to a ‘C’, 1-type expression can be assigned a new value. 
For example, in the case of a de-referenced pointer, a new value can be assigned to 
the pointer or the de-referenced expression. 


Variables are assigned as follows 

1 . Place the caret over the required expression to make it Active. 

2. Press ‘=‘. 

3. Enter the new value to the displayed dialogue box; this can be another expression 
if required. 

4. Cbek l 


In the example below, this facility was used to assign a new valueQit80002000 to 
the specified pointer. The de-referenced structure changes to reflect the amended 
value. 



Displayed Structures For Pointer Address 
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Amended Structures After Pointer Assigned New Variable 


IMPORTANT: The expression that you are assigning and the new valunjust 
have eompatible types. 


Note: Variables can be assigned whilst the Target is running. 


Expanding Or Collapsing A Variable 

Pointers, structures and arrays are variables which can be expanded or collapsed in 
the Local or Watch Panes and the Call Stack Display when you place the caret over 
them. 

If you expand apointer a line will be added below for the dereferenced pointer. For 
example if the pointer is to an integer, the dereferenced pointer will display that 
integer. 

An expandedstructure will display all the elements of that structure below it. 

For an expandedarray the second line of the display will display the first element of 
the array. 


To expand or collapse a variable: 

1. Select the Pane menu for the Local or Watch Panes. 

2. Choose the Expand or Collapse option from the menu. 
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► 


When shown in the Wateh Pane, expressions whieh ean be expanded or collapsed will 
be prefixed as follows: 


+ this indicates an expression that can be expanded 

this indicates that the expression is expanded and can be 
closed. 


This is followed by the expression’s type and value. 


To edit an expression, Shift +double-click or highlight it and press Return. 


Note: It is also possi 
collapse icons 


jle to expand or collapse an expression by using the expand or 
on the Pane toolbar or pressing SPACE. 




Note: Ctrl+SPACE or Ctrl+double-click will expandll the elements in an array. 


► 


Traversing An Index 

You can traverse an index if the caret is on an array element in the Eocal or Watch 
Panes. 

If an index is increased, the array will display tlnaext array element. 

Decreasing an index causes thf)revious array element to be displayed. 

To increase or decrease an index: 

1 . Select the Pane menu for the Eocal or Watch Panes. 

2. Choose the Increase Index or Decrease index option from the menu. 


Note: It is also possible to ex pand or co llapse a variable by using the increase index 
or decrease index icon on the Pane toolbar. 
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Adding A Watch 

The Watch Pane is used to evaluate and browse C type expressions. 

To add a watch or expression 

1. Make the Watch Pane the Active Pane. 

2. Select the Watch Pane menu from the Menu bar. 

3. Choose the Add Watch option from the menu. 

4. Type the required expression directly into the Add Expression dialog box or click 
the down arrow to display expressions which have been used previously. 



Add Watch Dialogue Box 

OK 

5. Enter or click the required expression and seled 

The Debugger also offers various ‘matching’ facilities whereby you can enter a partial 
value and the program will search the current and global scopes for those matching 
the specified criteria or browse all available symbols. These are described below in 

Using The Expression Manager 
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Note: It is also possible to add a watch by clicking on the add watch ic 
the Watch Pane toolbar or using the Hot Kejnsert. 



See Also: 

Using The Expression Manager 


► 


Editing A Watch 

Any of the C type expressions that you can enter into the Watch Pane can be edited 
as follows: 


1 . 

2 . 

3. 

4. 

5. 


Make the Watch Pane the Active Pane. 

Select the Watch Pane menu from the Menu bar. 
Choose the Edit Watch option from the menu. 
Select the watch to edit. 


Amend as necessary via the Edit Expression dialog and e1i l 
browsing and matching facilities are available via this dialogue box. 


. History, 


Note: It is also possible to edit a watch by clicking on the Edit Watch ic 
the Watch Pane toolbar. 



Note: To view variables in hexadecimal, right-click within the Pane and ‘toggle’ 
‘Hexadecimal/Decimal’ as necessary. A tick will appear alongside 
Hexadecimal when this option has been selected.Ctrl + Shift + T can also 
be used to toggle the mode displayed. You can also toggle the mode for a 
single expression viaCtrl + T. 


See Also: 

Using The Expression Manager 
Previously Entered Expressions History List 
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Deleting A Watch 

Any of the C type expressions entered into the Watch Pane can be deleted as follows 

1. Make the Watch Pane the Active Pane. 

2. Select the Watch Pane menu from the Menu bar. 

3. Choose the Delete Watch option from the menu. 

4. Select the watch and press Enter. 


Note: It is also possible to delete a watch by clicking on the Delete Watch ici 
on the Watch Pane toolbar or pressing DEL. 




Note: You can only delete a Watch at the root of the expression, not on any 
expanded part of it. 


Clearing All Watches 

All of the C type expressions entered into the Watch Pane can be removed in one 
action, as follows: 

1. Make the Watch Pane the Active Pane. 

2. Select the Watch Pane menu from the menu bar. 

3. Choose the Clear All Watches option from the menu. 


Note: You can also clear all watches by clicking on the Clear All Watches ic. 
on the Watch Pane toolbar. 


A 
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Debugging Your Program 


The Debugger helps you to detect, diagnose and correct errors in your programs. 

This is achieved via facilities which enable you to step and trace through your code in 
order to examine local and global variables, registers and memory. 

Breakpoints can be set wherever you need them at C and Assembler level and if 
required, these breaks can be made conditional on an expression. Additionally, 
selected breakpoints can be disabled for particular runs. 

Your choice of Views depends on the level at which you are debugging. For example 
it is appropriate to use a Register Pane for assembler debugging and a Local Pane 
when debugging in C. 
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Specifying The Polling Rate And Continual Update Rate 


It is possible to set the rate at whieh the Debugger eheeks the exeeption state of the 
Target, i.e. determine the granularity of diseovering an exception when the Target is 
running. 


Note: Even though checking the exception state has zero hit for some Targets, it is 
not recommended that you set this value belo\250 ms. 


It is also possible to specify the rate at which the Debugger updates information while 
the Target is running. This is particularly important for Targets which connect 
independently of a pollhost( ) since rapid connection rates may cripple the Target. It 
is measured in polling ticks, e.g. 250 x 4 ticks = a continual update rate of 1 second. 

If required, continual update (not polling) can be turned off altogether. 


► 


The rates are set as follows: 


1 . Select ContinualUpdate Rate from theProject option on the main menu or press 
Ctrl+I. A dialogue box displays the current polling rate in milliseconds: 



Update Rate Dialogue Box 


2 . 


If required, enter a new value and selecL___ 
debugging sessions and not as part of a Project. 


The rate is saved between all 


3. The continual update rate is measured in polling ticks; enter a new value if 
required. 


To turn off the continual update rate: 


De-select theContinual Update Rate; only the polling rate will still be active. 
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Forcing An Update 


During continual update, the information you see in the Debugger windows won’t be 
updated until the next connection; therefore, the slower the update rate, the longer it 
will be before exceptions can be spotted. However, it is possible to force an update 
by pressingCtrl+U, selecting theUpdate option fromDebug on the main menu or 


clicking the 



button on the toolbar. 


© SN Systems Ltd 


Nintendo 64 


Windows 95 Debugger 


Page 10-71 




Using The Expression Manager 



The Expression Manager Dialog is used to enter an expression, for example to add a 
watch to the Watch Pane or specify a location for a breakpoint. 

In summary, the Dialog provides the following facilities: 

• A history list of previous expressions 

• Name completion 

• Enhanced browsing features 

• The ability to select from various groups of symbols 

• Expression copying and pasting to/from the expression clipboard 

• Instant expression evaluation 


To access the Expression Manager: 

The dialog will be displayed whenever you select an option which requires you to 
specify an expression. The title bar will reflect the context from which it was called. 



Expression Manager Dialog 
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To specify an expression: 

1. Enter text or symbols to theCurrent Expressionbox. 

2. If you do not know the format of the required expression, elk " I (or 

press Alt+B) and the Symbol Browserwill display all symbols (and their details) 
in the current scope. SeeUsing the Symbol Browserbelow. 

3. A pull-down history list of the most recently entered expressions is also available 
from the Current Expressionbox. 

4. Select or specify as appropriate. 

5. Alternatively, if you know and have entered part of the expression, click 

] (or press Alt+C) and use the name completion facility; this will 

take the text fragment from the left of the cursor and attempt to match it with the 
start of the debugging symbols found in the current scope. Ilsingle match is 
found the text is replaced by the complete symbol. Where more than one match 
is found a separate window will show the matching symbols in alphabetical order. 


Add Expression 


ml 


Current Expression 
|Set 


3 


[ 


1 ! Matching Symbols | 

>n 

Name 

Type 

A 

liSetBdckColor 

null 


SetBlockFill 

null 


SetColorMatrix 

null 


SetData32 

null 


SetDefDispEnv 

null 


SetDefDrawEnv 

null 


SetDispMask 

null 


SetDQA 

null 


SetDQB 

null 


SetDrawArea 

null 

— 1 

SetDrawEnv 

null 


SetDrawMode 

null 


SetDrawMove 

null 


SetDrawOffset 

null 


SetFarColor 

null 


SetGeomOffset 

null 


SetGeomScreen 

null 


SetGraphDebug 

null 


SetGraphQueue 

null 


SetGraphR averse 

null 


SetIntrMask 

null 


SetIRO 

null 


SetlR123 

null 


SetLightMatrix 

null 


SetLineF2 

null 

d 



Browse... 


Help 


Expression Manager Displaying Matching Symbols 
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6. Select the symbol to be inserted into the expression; press ESC to cancel the 
operation. 

7. By default, all available symbols are matched during name completion, however, 
you can change this to matclonly symbols of a specific group by selecting an 
alternative from theSymbol Group list. The selection can be restricted to any of 
the following groups: 

All Symbols 

Globals 

Locals 

Functions 

Types 

Assembler Labels 


Note: The group selected here will also be the first one displayed by tSymbol 
Browser. See point 2 above andUsing the Symbol Browserbelow. 

8. Click when your expression is complete; it will be inserted into the 

relevant Pane. 


To evaluate an expression: 


At any time you can attempt to evaluate the current expression by clicking 

Evaluate »> | pressingAlt+E). If the expression can be evaluated, its memory 
address will be displayed in the adjacent window, otherwise a suitable error will be 
given. 
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Expression Manager Displaying Evaluated Expression 


To use the Expression Clipboard: 

1 . Click Current | pj-ggs Alt+Y) to copy the current expression into the 
Debugger’s Expression Clipboard; this can be recalled later within other 
Debugger components 

Note: The expression text is also copied into the Windows Clipboard to be used 
by other Windows applications. 

2. The contents of the Expression Clipboard can also be inserted into the current 
expression by clickin g-^^^^ Current | pj-ggsingAlt+P. 
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► 


To use the Symbol Browser: 

1. Click ’ I (or press Alt+B) and the Symbol Browser will display all 

symbols (and their details) in the current scope. 

The details are as follows: 


Name 

Type 

Class 

Location 

Dims 

Tag 


The name of the symbol as it would appear in your code. 

For storage variables - type (eg int, float); For functions - return typ|e 
‘C’ class of he symbol, e.g. automatic, static, union, typedef etc. 

The memory location or position relative to the stack the symbol 
refers to, if applicable to the symbol. 

The number of dimensions of the symbol if it represents an array anjl 
also the size of each of its dimensions. 

The structure or enumerator tag if applicable. 


2. You can restrict the number of symbols which will be displayed by selecting a 
particular group of symbols from the pull-down menu and clicki_z!2!!!fl_ 


3. In addition, the ‘wildcard’ matching facility can be used in conjunction with the 
specified symbol group to restrict the display to particular symbols. Enter 
wildcard text in the edit box . A^’ character will match 0 to any number of text 
characters, while a ?’ character will match any single text character. All other 
characters will only match the equivalent text characterjn^?n’ will match all 
symbols in the specified symbol group that start witin®, end in b’ and have at 
least one character between, for examploAain’ . 


By default, all symbols are sorted and displayed in alphabetical name order. 
However, if you click on the heading name for any of the details columns, the 
symbols will be sorted by the relevant column heading. 

4. Click or press RETURN on a symbol name and it will be inserted into the 
Current Expression box in the Expression Dialog. 

5. Click to insert the expression in the relevant Pane. 
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To specify multiple expressions: 

1. If required, more than one expression and symbol can be entered in the Current 
Expression box. 

2. Use the mouse and Ctrl and/or Shift keys to make a specific selection and then 
press RETURN to insert it in theCurrent Expressionbox; the expressions will 
be represented by appropriate text in angled bracketscMulti !>’ and ‘<Multi 
2>’ as shown below: 



Add Expression Dialog Displaying Representation Of Multiple Expressions 

Up to three multiple selections can be specified at a time. 

Single expressions can be specified alongside multiple groups. 

If a group is deleted in theCurrent Expressionbox, all symbols and expressions 
within the group will be removed. 

3. When completed, click to insert the expression(s) in the relevant 

Pane. 
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Setting Breakpoints 


Breakpoints can be set in Source and Disassembly Panes; they appear in the Pane as 
a different coloured bar. 


A Project can have many breakpoints set and they are saved when the Project is 
saved. They are restored relative to Assembler labels wherever possible; this ensures 
they are preserved even when you alter the source code and rebuild. 


The Debugger supports a Paneand Tool based Breakpoint Plug-In. 

The Breakpoint Manager Paneand Breakpoint Manager Dialog allow you to 
view all current breakpoints. They also allow you to set breakpoints anywhere in 
memory and alter a breakpoint’s type and settings. 


There are four types of breakpoint: 


Absolute 

Counter 

Countdown 


Conditional 


The PC stops when it arrives at the breakpoint. 

The counter is increased by one every time the PC passes the 
breakpoint. This does not stop the PC. 

The counter is decreased by one from an initial user-set value every 
time the PC passes the breakpoint. When the counter reaches zero the 
PC stops at the breakpoint. 

The PC stops at a conditional breakpoint only if a user-specified 
expression evaluates as TRUE. 


To access the Breakpoint ManageFane: 

1 . Right-click within a Source or Disassembly Pane and sel^her from the 
displayed sub-menu. Left-click within the empty Pane. 

The Plug-In Manager will display the currently installed Plug-Ins. 
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Plug-In Manager 


2. Select the Breakpoint Manager Pane and die I . 

The selected Pane displays a list of the breakpoints which are currently set. 
Where relevant the following information is shown for each one: 


Address 

Label 

Expression 

Count 

Type 

Enabled 


The memory location of the breakpoint. 

The nearest label to the breakpoint. 

Any expression used to create a conditional breakpoint. 

The number of steps since the PC passed the breakpoint or until 
the breakpoint is reached. 

The brealpoint type. 

The current state - Yes or No. 


The breakpoint’s type is also reflected in the icon displayed next to its address. 
This icon changes to a ‘triggered’ icon when the breakpoint stops the PC. 
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Breakpoints 


Address 

Label 

1 Expression 

Count 

Type 

Enabled 

■ 0x8004G37c 

tbo_numpoints 

N/A 

0 

Absolute 

Yes 


Breakpoint Manager Pane 


To access the operations menu for a breakpoint: 

Right-click over the required breakpoint. 

A sub-menu is displayed, from which you can carry out the following actions: 

^ To add a breakpoint: 

In the displayed Expression Manager enter the memory address where you wish 
the breakpoint to appear. SeeUsing The Expression Managerfor further 
details. 

^ To remove a breakpoint: 

Toggle the option for the selected breakpoint. 

^ To disable a breakpoint: 

Toggle the option for the selected breakpoint. 

^ To alter breakpoint properties: 

1. The Breakpoint Dialog will display the current properties for the selected 
breakpoint. 
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2. Change theBreakpoint Type if required. IfCountdownis chosen you must 
enter a value to theBreakpoint Count box. 

You must specify aBreak expressionif theBreakpoint Type is 
Conditional. Use the adjacent browse button to search for available 
symbols. 

3. I can be used to reset the Breakpoint Count to zero wheCownterhas 
been selected. 

4. De-select or select theEnabled box if required. When this check box is set 
the breakpoint is enabled and only these will be included in a debugging run. 

O3r*iO0l I 

5. Use I to leave the dialogue box without saving the changes you 

have made. 

6. Click when the amendments are complete. 


Note: This dialog is also accessible via the Edit Breakpoint option from the Source 
or Disassembly Panes. 


To access the Breakpoint ManageDialog: 

From the mainTools menu, select the Breakpoint Manager Dialog. This performs 
identical functions to the Pane but uses buttons as well as the right-click menu. It 
provides a quick means of displaying and amending breakpoint settings without the 
necessity of switching Pane types. 
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It is also possible to directly set or edit a breakpoint as follows: 

1. Make a Source or Disassembly Pane Active. 

2. Click on the instruction or line at which you want to set the break or amend an 
existing one. 

3. Select the Source menu from the Menu bar. 

4. Choose the Toggle or Edit breakpoints option from the menu. 


Note: An Absolute breakpoint will be inserted by default when the Toggle 

breakpoints option is used. Us£dit breakpoints and a relevant selection to 
insert any other type. 


A breakpoint can be removed by clicking on the colour bar and toggling the menu 
option taken to create it. 


Note: Breakpoints can also be set and removed via thE5 key or the set / unset 

1% I 

breakpoint icons on the Pane toolba ^ 1 


Note: The I button on the toolbar will clear all breakpoints, Note however that 
if you have upgraded a previous beta version, this button will not be available 
unless you have customised the toolbar. 
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Note: Double-clicking on a breakpoint in a Source and Disassembly Pane will goto 
that breakpoint. De-selecting th^espond to breakpoint eventin the 
Pane’s context menu however, will switch this property off. The information 
is saved with the View or Project. 
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Using The Call-Stack Display 


The Call-Stack Display Pane Plug-In allows you to view the whole of the stack and 
step up and down it to a particular context. 

The benefit of this is that it allows you to see the functions being called and where 
they were called from. It is also possible to see the parameter types and values that 
were passed to a function. 


Note: The Debugger will only provide call stack information when it detects there is 
a valid frame pointer and there are symbols available for the current function. 


To display the Call Stack: 

1. Right-click within any Pane and sele#ther from the displayed sub-menu. Left- 
click within the empty Pane. 

The Plug-In Manager will display the currently installed Plug-Ins. 

2. Select the Call-Stack Display Plug-In and di e 



Call-Stack Display 


The Call-Stack Display dialog provides a view of the whole stack; an icon (a 
green triangle) points to the current context. Other contexts are designated by a 
red triangle. Parameter details are highlighted by a red or green circle depending 
on whether they are part of the current context or not. 
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The Windows 95 tree control functions have been used in this dialog to show 
information about the stack. You can therefore quickly see which context the 
stack is in and which function calls have been placed on the stack. You can 
expand a branch if you wish to view more information about a function call. If 
they are available, branches will be shown for function return values, parameter 
types or parameter values. 


► 


► 


► 


To use the scroll bar: 

1 . A scroll bar on the right of the tree control allows you to view various portions of 
the stack. 

2. When you click on a stack context, the pointer will move to that context and 
reposition the view on the stack accordingly. 


To switch contexts: 

1. You can alter the context (machine state) to reflect a previous function call by 
clicking on a particular context in the tree control. 

2. The green icon will be repositioned to reflect that the machine’s current state has 
been changed and other windows will be updated accordingly. 


Note: You can customise the tool bar to include the following stack stepping 
icons: 



- To increase the stack level context. 

- To decrease the stack level context. 


To expand a branch: 

1. Right-click within the Pane. 

2. A pop-up menu allows you to display return values, parameter types or parameter 
values. Left-click an item to select it and a check mark will appear alongside it. 
Left-click again to de-select the option. 

3. If a cross is shown to the left of displayed parameters, this means that the 
parameter is a structure, pointer or an array. In the same way that parameters can 
be expanded in a watch window, clicking on this cross will also reveal the derived 
types and values. 


Note: When the autoexpand menu item is selected, parameter details associated 
with a context will be displayed, provided that at least one parameter 
detail option is selected. 
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To copy a selection to the Expression Clipboard: 

1. It is possible to select an item from the Call Stack Display and copy it into the 
Expression Clipboard for subsequent use in a different application. 

2. Select the item to be copied. 

3. Press Ctrl + C or right-click and select theCopy option from the displayed pop- 
up menu. 

Note: The selected expression also appears on the Debugger’s status bar. 

To change properties of the Call Stack: 

1. Right-click within the Pane. 

2. A pop-up menu allows you to display return values, parameter types or parameter 
values. Eeft-click an item to select it and a check mark will appear alongside it. 
Eeft-click again to de-select the option. 


Note: Properties selected via the right-click pop-up menu are saved when the Project 
is saved. 
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Stepping Into A Subroutine 


The Step Into commandallows you to trace the execution of the program one step at 
a time and so isolate any bugs that might be present. 

When you Step Into a subroutine call, the Program Counter moves to the start of the 
subroutine and displays the relevant code. At the end of the subroutine you will be 
returned to where it was called from. 

At Assembler level a debugging step is the execution of a singhestruction. 

At Source level, oneline at a time will be executed in each step and any subroutines 
or calls within that line will be stepped into. 

The current stepping mode is indicated b^RC or DIS on the far right of the status 
bar; the Debugger will change this to the appropriate mode when either a Source or 
Disassembly Pane become active. You can override this however by usiB^l + M 
to toggle between the two. 


Note: If the mode is SRC and a Source level step cannot be performed, a 
Disassembly level step will be performed instead. 


To Step Into a subroutine during debugging: 

1 . Select the Debug menu from the Menu bar. 

2. Choose the Step Into option from the menu. 


Note: Alternative ways of Stepping Into a subroutine are to use the Step Into icon 


on the Unit toolbar (at the bottom of the Debugger window l - 


or to press 

F7. Note that it is possible to use the Step Into icon for a non-Active View. 
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Stepping Over A Subroutine 


When you use the Step Over eommapdhe subroutine is executed but not displayed 
and the Program Counter moves to the next line of calling routine code. 

At Assembler level a debugging step is the execution of a singhestruction. 

At Source level, one line at a time will be executed in each step and any subroutines 
or calls within that line will be performed. 

The current stepping mode is indicated b^RC or DIS on the far right of the status 
bar; the Debugger will change this to the appropriate mode when either a Source or 
Disassembly Pane become active. You can override this however by usiE^l + M 
to toggle between the two. 


Note: If the mode is SRC and a Source level step cannot be performed, a 
Disassembly level step will be performed instead. 


To Step Over a subroutine: 

1. Select the Debug menu from the Menu bar. 

2. Choose the StepOver option from the menu. 


Note: Alternative ways of Stepping Over a subroutine are to use the Step Over icon 


by the Unit mend I or to press F8. Note that you can use the Step Over 
icon for a non- Active View. 
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Stepping Out Of A Subroutine 


The Step Out Of command returns you to the command after the statement that 
called the current function, i.e. it unpicks the stack one level, calculates the Program 
Counter at this level, sets a temporary breakpoint at this address, sets the stack level 
to 0 and then runs the target. 


Note: In order to use the Step Out command, the Debugger requires full symbol 

information for the function you are in and you must not be executing prolog 
or epilog code. 


To Step Out of a subroutine: 

1 . Select the Debug menu from the Menu bar. 

2. Choose the Step Oit option from the menu. 


Note: Alternative methods of Stepping Out of a subroutine are to click on the Step 
Out Of icon on the Pane toolbai I or to use the Hot KeyF12. 
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Running To The Current Cursor Position 


► 


The Run to Cursor command can be used during debugging within the Source and 
Disassembly Panes. 

To run to the current cursorposition 

1. Make a Source or Disassembly Pane active. 

2. Click on the displayed code at the point you want to run to. 

3. Select the Source or Disassembly menu from the Menu bar. 

4. Choose the Run To Cursor option from the menu. 


If the Unit does not reach the cursor position it will continue running. 


Note: Alternative methods of running to th e cursor are to click on the Run To 

or to use the Hot KeyF6. 


Cursor icon on the Pane toolbaii= 


Note: You can use Run To Cursor while the Unit is running to make it stop at the 
cursor position. 
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Running Programs 


► 


The Run command causes the CPU of the specified Unit to start running. 

It will continue until it meets a breakpoint, a processor exception or is stopped by the 
Stop or Run To Cursor commands. 

During a debugging run the various Panes will show the progress of the run. 

To start the program running 

1. Select the Debug menu from the menu bar. 

2. Choose the Go option from the menu. 


Note: Alte rnativ e ways to start the run are to click the Start button on the relevant 
Unit toolbar. 




or to press F9. F9 will also stop the Target if it is running. 


Stopping A Program Running 


The Stop command halts the CPU of the specified Unit as soon as possible. 


It is specified as follows 

1 . Select the Debug menu from the Menu bar. 

2. Choose the Stop option from the menu. 


Note: Alternative ways to stop the run are to click the Stop button on the relevant 


Unit toolbar 


or to press Esc. 
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Moving The Program Counter 

The program counter (PC) can be set via the Set PC command. 

This command moves the program counter to the current cursor position. 

^ It is found on the Pane menus for Source and Disassembly Panes and is set as 

follows 

1. Make a Source or Disassembly Pane Active. 

2. Place the caret where you wish the PC to move to. 

3. Click the right hand mouse button to call the Pane menu. 

4. Select the Set PC option from the menu. 

With this command, no instructions are executed between the previous and new PC 
position. 

The opposite command tqSet PC is Goto PC which takes the cursor to the position 
of the Program Counter. 


Note: An alternative way to activate the Set PC command is by using the Hot Key 

Shift+Tab. 
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Moving The Caret To The PC 

The caret point can be placed at the program counter address via tlfioto PC 
command. 

This is found on the Pane menus for Source and Disassembly Panes. 

^ To Set The PC 

1. Make a Source or Disassembly Pane Active. 

2. Click the right hand mouse button to call the Pane menu. 

3. Select the Goto PC option from the menu. 

Goto PC is the opposite command tqSet PC which sets the Program Counter to the 
value at the current caret position. 

Note: Alternatively, pressing the ‘space’ bar wiflirectly place the caret point at 


the program counter address. 
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Moving To A Known Address Or Label 


The Goto command is available on the Source, Disassembly and Memory Pane 
menus. It is used to put the caret and PC at a known address, label name, register 
name or value of a specified C expression as described below: 

1. Make the Source, Disassembly or Memory Pane Active. 

2. Click the right hand mouse button to call the Pane menu. 

3. Select the Goto option from the menu. 

4. The Goto Expression dialogue box appears. 



Go To Expression Dialogue Box 


5. 


6 . 


Type the required expression directly iCurrent Expressionbox or click the 
down arrow to display expressions which have been entered previously. Various 
browsing and matching facilities are also available via this dialog box. iMng 
The Expression Managerfor further details. 


Enter or select the required expression and elie l . 

hexadecimal address must be prefixed with the string ‘Ox’ 


Note that a 


As the Goto action will take you to thevalue of the specified expression, note the 
consequences when you enter a name containing C debug informatiasiwell as an 
Assembler label. 
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For example, if ‘_ramsize’ is specified you will be taken to rtialue of _ramsize, not 
to where it is defined. This is because the C expression evaluator sees the C 
definition of _ramsize first and then evaluates it. TBoto this address, you must 
enter either ‘&_ramsize’ or ‘:_ramsize’. 

Alternatively, you coulcGoto ‘main’ (as functions evaluate to their address); to 
Goto an offset from main, enter: ‘:main+offset’, ‘&main+offset’ or 
‘(int)main+offset’. This is because ‘main’ by itself has the ty^ ( ) which cannot 
be added. 


Note: When you have successfully ‘gone to’ an expression in a Memory Pane, the 
‘pointed to’ word is enclosed in a box. This will remain until yOcto 
something else or anchor the Pane to an expression. 



See Also: 

Anchoring Memory Panes 
Expression Evaluation Features 
Using The Expression Manager 
Previously Entered Expressions History List 




Note: Alterna 
toolbar 

tive] 

y, you can activate the Goto command via the Goto icon on the 
or the Hot Key Ctrl G. 
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Expression Evaluation Features 


Register Names 

Register names can be specified in any dialogue box where expressions can be 
entered. By default, the evaluator looks for C symbols first, so any variables which 
are the same as register names will be shown instead. If a name is being interpreted 
as a register it will be prefixed by a ‘$’. 

It is recommended that you use this ‘$’ prefix wheentering register names to 
explicitly tell the evaluator that it is looking at a register. 


Note: Registers have a C type of ‘int’. 


Typecasts and Typedefs 

Typecasts can be entered to an expression via the usual C syntax. 

If you entered ‘(int*)$fp’ to a Watch Pane you would see the following: 

+int*(int*)$fp = OxSOOOffOO 

Typecasting also works for structure tags; however, you are not required to enter 
the keyword ‘struct’ when casting to a structure tag. 

You would expect to see the following when typecasting to a structure (or class): 

-Tester* (Tester*)$fp = 0x807ff88 
-Tester 

+unsigned char* m_pName = 0x00000645 
-i-unsigned char* mpLongName = OxFFFFFFFF 

You can also cast to typedefs; for example, entering ‘(daddr_t)p’ will produce: 

long (daddr_t)p = 0x00003024 
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Labels 

Labels can also be included in a C expression. The evaluator looks for C level 
information first and then label information. If it finds a label it will prefix it with 


It is recommended that you use this prefix wheentering labels to explicitly tell the 
evaluator that it is looking at a label. 


Note: Labels have a C type ofint’. 


Functions 

If you include a function name in an expression, its value will be the same as its 
address. It will appear in a Watch window as follows: 

int ( ) main = (...) (OxSOOlOBFC) 


Note: This is contrary to C where the value of a function, is what is returned from 
the function when it is executed. 


Note: It is recommended that you access the address of a function via the ‘&’ 
operator or the Assembler label. 


Expression Evaluation Name Resolution 

In summary, the search order for a name in an expression is as follows: 

1. Escaped Register Names (prefix ‘$’) 

2. Escaped Eabel Names (prefix ‘:’) 

3. C Names 

4. Register Names 

5. Eabel Names 
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Previously Entered Expressions History List 


Once an expression has been speeified via an Expression Manager dialogue box, it 
will be stored in a history buffer. 

When you next aecess one of these dialogue boxes, cliek the down arrow to display 
listing of these values. 


At this point you ean enter a new expression to the dialogue box or seleet one from 


the list and cliek 


OK 


The seleeted expression ean also be edited at this point. 


Note: The most recent expressions used are held at the top of the list. 


Anchoring Panes To The PC 


► 


By default the Source and Disassembly Panes are anchored to the Program Counter 
(PC). 

This means that whenever possible the instruetion or line at the PC is always 
displayed in the Pane. 


The Follow PC property is toggleds follows 

1. Make a Souree or Disassembly Pane Aetive. 

2. Click the right hand mouse button to eall the Pane menu. 

3. Select the Follow PC option from the menu. 


Note: This option is also available from the Source and Disassembly Pane toolbar 
or from the Source or Disassembly menus on the Menu bar. 
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Anchoring Memory Panes 


Anchoring a Panehas the same function as usin^oto on every Debugger update. 


To anchor the Pane: 

1. Select Anchor... from the Pane menu or presOrl+A when a Memory Pane is 
active. 

2. Enter an expression. 

3. Select I ^1? 

The specified expression will appear in an indicator bar on the Pane. If this goes red, 
the expression cannot be evaluated in the current scope. Otherwise, the Pane will be 
‘anchored’ to the value of the expression and a box will be drawn around the anchor 
point. 

You can edit the expression by clicking the indicator. 

To turn off anchoring: 

1. Call up the Anchor dialogue box. 

2. Clear the box. 

3. Select I 
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Identi^ing Ch anie d Information 


Any changes to variables since the last debugging step are displayed in a colour of 
your choice on allPanes except for Disassembly and Source. 

This colour is set via the Set DefaulColour option from theView menu. 

See Also: 

Changing colour schemes in Views 


Closing The Debugger Without Saving Your Changes 


The Quit option on the Project menu stops the Debugger running but does NOT save 
the current Project. 


To close the Debugger without saving youcrhanges: 

1 . Select the Project menu from the Menu bar. 

2. Choose the Quit option from the menu. 

Note: When you close the Debugger, it will remember the current working directory 
and restore this when it is re-opened. 
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Closing The Debugger And Saving Your Changes 


The Exit option on the Project menu saves the current Project at the latest state and 
stops the Debugger running. 


To close the Debugger and save your changes 

1 . Select the Project menu from the Menu bar. 

2. Choose the &it option from the menu. 

Note: It is also possible to close the Project by clicking on thSi icon on the system 
menu shown in the top right corner of the Debugger window. 


Note: Next time you open the Debugger the last Project you saved will be launched 
automatically. 


Note: When you close the Debugger, it will remember the current working directory 
and restore this when it is re-opened. 


See Also: 

Saving Your Project 
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CHAPTER 11 

The PSYLINK Linker 


The LinkerPSYLINK is a fully-featured linker which works with all processor types. 
You can split complex programs into separate, manageable sub-programs which can 
be recombined bjPSYLINK into a final, single application. 


This chapter discusses the linker together with the Librarian utility, under the 
following headings: 


• Command Line Syntax 

• Linker Command Files 

• XDEF, XREF and PUBLIC 

• GLOBAL 

The Linker-associated Assembler directives (XDEF, XREF, PUBEIC and GEOBAE) 
are repeated here for ease of reference. 
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PSYLINK Command Line 


Description The PSYLINK link process is controlled by a series of parameters on the command 
line and optionally by the contents of a Linker command file. The syntax for the 
command line is as follows: 


Syntax PSYLINK {switched objectfile(s),output,symbolfile,mapfile,libraries 

If a parameter is omitted, the separating comma must still appear unless it is the last 
parameter of the line. 


Switches Switches are preceded by a forward slash X/and are as follows: 


/c 


/d 

/e symb=value 

/i 

!\ path 

/m 

/n maximum 


/o address 


Tells the linker to link case sensitive; if it is dttied, all names 
are converted to upper case. 

Debug Mode - perform link only. 

Assigns value to symbol. 

Invokes a window containing Link details. 

Specify path to search for library files. 

Output all external symbols to the map file. 

Set the maximum number of object files, or library modules, 
that can be linked, 1 to 32768; default = 256 
Higher values require larger amounts of memory. 

Set an address for anORG statement. 


/p Output padded puE binary object codeGRGed sections of 

code are separated with random data, (equivalent c/j)b 
switch on assembler) 

/ps Output ASCII representation of binary file in Motorola 

s-record format. 


/s 


All sections must be in defined groups. 


/u number Specify iheunit numberm a multi-processor target. 

/v Enable automaticoverlay recognition by the Debugger 
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Objectfile(s) 

Output 

Symbolfile 

Mapfile 

Libraryfiles 


/wl Warn of multiple definitions in libraries. 

/wm Warn of multiple declarations of the same C variable, 

/x address Set address for the p’ogram to commence execution, 

/z Clear all requested BSS memory sections. 


A list of object files, output by the Assembler using tliboption. File names are 
separated by spaces or plus (+) signs; if the file starts with sign, it signifies the 
name of a Linker command file. See below for a description of the format. 

The destination file for the linked code; if omitted no output code is produced. If the 
output file name is in the format T:, the linked code is directly sent to the target 
machine -n specifies the SCSI device number. 

The destination file for the symbol table information used by the Debugger. 

The destination file for map information. 

Library files available - see The PSYLIB Librarian chapter for further information. 
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Linker Command Files 


Command files contain instructions for the Linker about source files and how to 
organise them. The Linker command file syntax is much like the Assembler syntax, 
with the following commands available: 


Commands 

INCLUDE 

filename 

Specify name of object file to be read. 


INCLIB 

filename 

Specify library file to use 


INCBIN 

filename 

Specify binary file to be included 


ORG 

address 

Specify ORG address for output 

name 

EQU 

value 

Equate name to value 


REGS 

pc=address 

Set initialPC value 

name 

GROUP 

attributes 

Declare group 

name 

SECTION 

attributes 

Declare section with attributes 


SECTION 

name[,group] 

Declare section, and opfibnally specify its 
group 

name 

ALIAS 

oldname 

Specify anALIAS for a symbol name 

UNIT 


unitnum 

Specify destination unit number; this must 

always be 0 for the Nintendo. 



Group attributes: 

BSS 

O^G{address) 

0^i{address) 

OBJO 

OW'ERigroup) 
F1LE{" filename”) 
SlZE(maxsize) 


group is uninitialised data 
specify group's org address 
specify group's obj address 

group's obj address follows on from previous group 
overlay specified group 
write group's contents to specified file 
specify maximurmllowable size 


Remarks 


• The directiveINCBIN allows direct inclusion of binary data. The command 
format is: label INCBIN file, section [, alignment ] e.g. 

grdata incbin "graphics .bin", • data 

This will put the contents of binary filgraphics .bin into section .data and 
define labelgrdata to be at the start of this data. 

The optional alignment specifies the data’s alignment as a power of 2, for 
example in: 

grdata incbin "graphics .bin", . data, 4 
the data will be aligned on a 16 byte boundary. 
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• Both INCLUDE and INCLIB statements can specify a prefix to be added to all 
the section names specified in a module/library, for example, 

include "11 . ob j", levell 

will cause all sections mentioned in the fiM . ob j to have levell prefixed 
onto them so . text becomes levell .text , etc. 

This removes the need to use the previously usedWa, s... option in 
ccn64/ccpsx/etc. 

If INCLIB has a prefix specified then all used modules from that library will have 
the prefix added to their section’s names. 

• The Linker will now define global labels to allow the user to access the base 
address and size of each section and group. This is done by prefixing each group 
and section name with _ (underscore) and addin^ob j ,_org and_slze onto 
the end of the name to produce three names giving thsb j , org and size of 
the group/section respectively. Any .(dot) characters in the name will be 
converted to _ (underscore) characters. 

For example, the existence of the standard section .text will result in the creation 
of the labels ^text_obj text org and ^text_slze . 


Note: Two leading underscores, one explicitly added and one from converting 
the 


To access these names from C, declare the name as an external and then take its 
address to get the value, e.g. 

memset(& bss obi. 0, (Int) & ^bss_slze) ; 

will clear thebss section to 0. 

• Sections within a group are in the order that section definitions are encountered 
in the command file or object/library files. 

• Any sections that are not placed in a specified group will be grouped together at 
the beginning of the output. 

• Groups are output in the order in which they are declared in the Linker command 
file or the order in which they are encountered in the object and library files. 

• Sections which are declared with attributes, (i.e. not in a group) in either the 
object or library files, may be put into a specified group by the appropriate 
declaration in the Linker command file. 
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Examples 

include 

"inp . ob j " 


include 

"sort.obj " 


include 

"out . ob j " 


org 

1024 


regs 

pc=progstart 

comdata 

group 

word 

code 

group 


bssdata 

group 

bss 


section 

datal, comdata 


section 

data2 , comdata 


section 

coded, code 


section 

code2, code 


section 

tables, bssdata 


section 

but fers, bssdata 

Linker Associated Directives. 

GLOBAL 


Description The GLOBAL directive allows a symbol to be defined which will be treated as either 
an XDEF or an XREF. If a symbol is defined aGLOBAL and is later defined as a 
label, it will be treated as aiXDEF. If the symbol is never defined, it will be treated 
as an XREF. 


Syntax GLOBAL symboJ[,symboJ\ 

See Also XREF, XDEF, PUBLIC 

Remarks This is useful in header files because it allows all separately assembled 
modules to share one header file, defining all global symbols. Any of these symbols 
later defined in a module will bXDEFed, the others will be treated a^REFs. 
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XDEF, XREF and PUBLIC 


Description If several sub-programs are being linked, use XDEF, XREF and PUBEIC to refer to 
symbols in a sub-program which are defined in another sub-program. 


Syntax 


XDEF symboli,symboI\ 

XREF symboli,symboJ\ 


PUBLIC on 
PUBLIC off 


Remarks 

• In the sub-program where symbols are initially defined, tSd)EF directive is 
used to declare them as externals. 

• In the sub-program which refers the symbols, thXREF directive is used to 
indicate that the symbols are in another sub-program. 

• The Assembler does not completely evaluate an expression containingXREFed 
symbol; however, resolution will be effected by the linker. 

• The PUBLIC directive allows the programmer to declare a number of symbols as 
externals. With a parameter of on, it tells the Assembler that all further symbols 
should be automaticall^DEFed, until aPUBLIC off is encountered. 

Examples Sub-program A contains the following declarations : 

xdef Scores, Scorers 


The corresponding declarations in sub-program B are: 


xdef 

PointsTable 

xref 

Scores, Scorers 


Origin 

public 

on 

MainChar 

Force 

dew 

speed*origin 

Rebound 

dew 

45*angle 


public 

off 
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Example Linker Command File for GNU C Program 



org 

$80010000 

text 

group 


bss 

group 

bss 


section 

.rdata, text 


section 

•text, text 


section 

•ctors, text 


section 

•dtors, text 


section 

•data, text 


section 

•sdata, text 


section 

.sbss, bss 


include 

ob jf ilel . ob j 


include 

ob jf ile2 . ob j 

inclib 

c : \n64\lib\libsn . lib 


regs 

PC= SN ENTRY POINT 
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CHAPTER 12 

The PSYLIB Librarian 


If the Linker eannot find a symbol in the files produeed by the Assembler, it ean be 
instructed by a Linker command line option to search one or more object module 
Library files. 

This chapter discusses Library usage and thPSYLIB library maintenance program: 


• PSYLIB Command Line Syntax 

• Using the Library feature 
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PSYLIB Command Line 


Description The Library programPSYLIB.EXE, adds to, deletes from, lists and updates 
libraries of object modules. 

Syntax PSYLIB {switched library module... module 

where a switch is preceded by a forward slash (./) 

See Also PSYLINK 


Switches 


Library 


/a Add the specified module(s) to the library, replacing any already present 
/d Delete the specified module(s) from the library 

/I List the module(s) contained in the library (all will be listed if not specified) 
/Iv List specified library modules including symbols, if changed 
/u Update the specified modules in the library 

/x Extract the specified modules from the library (extracts all modules if no 

module list given) 

Note: Thedv switch shows symbols in the order they’re declared in the modules. 
XBSS-type symbols appear with an asterisk before the name, e.^.fbuff’. 

The name of the file to contain the object module library. 


Module list The object modules involved in the library maintenance. 


Using the Library feature 

• To incorporate a Library at link time, specify a library file on the Linker command 
line - see chapter 12. 

• If the Linker locates the required external symbol in a nominated library file, the 
module is extracted and linked with the object code output by the Assembler. 
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CHAPTER 13 

The CCN64 Build Utility 


CCN64 is a build utility to execute the C Compiler, Assembler and Linker. 
CCN64 makes use of theASN64 Assembler to process the assembly syntax 
produced by the GNU C Compiler. It is discussed in the following sections: 

• CCN64 Command Line 

• Source Files 
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CCN64 Command Line 


Description CCN64.EXE is a utility that simplifies the process of running the separate 'C 

compiler passes and then assembling and linking the compiler output. UsfifgN64 
you need only specify the input files and the output format you require, afiCN64 
itself will execute the tools required to generate the output. 


Syntax CCN64 {options ! filename filename...]] 

The command line consists of a sequence of control options and source file names. 
Options are. preceded by a minus sign ()■; andfilenames are separated by commas. 

Long command lines can be stored in separate control files. These can then be used 
on the command line by using a ‘ @ ’ sign in front of the control file name. 


Options Control 
-E 

-S 

-c 


-Ipath 


Pre-process only. If no output file is specified output is send 
to the screen. 

Compile to assembler source 

Compile to object file. If an output file is specified, then all output is 
sent to this file. Otherwise it saved as the source file name with an 
.OBJ extension. 

Specify extra include path for pre-compiler. 


Debug 

-g... Generate debug information for source level debugging 


Optimisation 

-OO 

-O or -01 
-02 


-03 


No optimisation (default) 

Standard level of optimisation 
Full optimisation 

Full optimisation and function in-lining. 


General 


-W... 

-Dname=val 

-Uname 

-v 

-f... 

-m... 


Suppress all warnings 

Define pre-processor symbohame, and optionally to the value 
specified. 

Undefine the pre-defined symbaiame before pre-processing starts 
Print all commands before execution 
Compiler option 
Machine specific option 
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Linker 

-Uibname Include specified lihrar^ibname when linking 

-X... Specify linker opion 

-odestin Specify the destination. Either a file (e.g. prog.cpe), or target (e.g. 
tO:) can be specified 

See GNU C documentation for full description 

Example CCPSX -v -g -Xo$80010000 main.c -omain . cpe, main . sym 

This example will execute the compiler to compile the source fMAIN.C ,then run 
ASN64 to produce the object file and finally will ruRSYLINK to produce an 
executable and symbol filelV^AIN.CPE and MAIN.SYM respectivelyjORGd to 
the specified address. The-v switch will causeCCN64 to echo all commands it 
executes to stdout. The-g switch will request full debug info in the symbol file. 

CCN64 0main.cf -omain 

This will force CCN64 to use the contents of thMAIN.CF file on the command 
line, before the -o option. 
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Source Files 


The specified source files can be either C or assembler source files, or object files. 
CCN64 decides how to deal with a source file based on the files extension. The 
following table describes how each file extension is processed: 


.c 

Passed through 

a 

Passed through 

.cc 

Passed through 

.cpp 

Passed through 

.ii 

Passed through 

.ipp 

Passed through 

.asm 

Passed through 

.s 

Passed through 

.other 

Passed through 


C pre-processor, C compiler. Assembler, Linker 
C compiler. Assembler, Linker 
C pre-processor, C-i-i- compiler. Assembler, Linker 
C pre-processor, C-i-i- compiler. Assembler, Linker 
C-t-i- compiler. Assembler, Linker 
C-I-I- compiler. Assembler, Linker 
C compiler. Assembler, Linker 
Assembler, Linker 
Linker 


Remarks 

• The PC file system is not case sensitive so the case of the extension has no effect. 
The UNIX file system is case sensitive so the case of the extension is important. 

• Various command line switches can stop processing at any stage, eliminating 
linking, assembling or compiling. 

• The -X option can be used to override the automatic selection of action based on 
file extension. 

• Files with extensions that are not recognised are treated as object files and passed 
to the linker. This includesOBJ files, the standard object file extension. 

• Several different source files, which may have different file extensions, may be 
placed on the command line. 
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CHAPTER 14 

The PSYMAKE Utility 


PSYMAKE is a make utility which automates the building and rebuilding of 
computer programs. It is general purpose and not limited to use with this system. The 
utility is discussed under the following headings: 

• Command Line Syntax 

• Format of the Makefile 
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PSYMAKE Command Line 

Description PSYMAKE only rebuilds the components of a system that need rebuilding. Whether 
a program needs rebuilding is determined by the file date stamps of the target file and 
the source files that it depends on. Generally, if any of the source files are newer than 
the target file, the target file will be rebuilt. 

Syntax PSYMAKE [switched [target file] 

or 

PSYMAKE @makefile.mak 

Switches Valid switch options are : 

fb Build all, ignoringiates 

/d name=string Define name as string 

a filename Specify theMAKE file 

/i Always ignore error status 

/q Quiet mode; do not print commands before executing them 

/x Do not execute commands - just print them 

If no /f option is specified, the default makefile makefile. If no extension is 
specified on the makefile narpeMAK will be assumed. 

If no target is specified, the first target defined in the makefile will be built. 
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Contents of the Makefile 


The Makefile consists of a series of commands, governed by explicit rules, known as 
dependencies, and implicit rules. When a target file needs to be buP^YMAKE 
will first search for a dependency rule for that specific file. If none can be found, 
PSYMAKE will use an implicit rule to build the target file. 


Dependencies 

A dependency is constructed as follows : 

targetfile : [ sourcefiles] 

[ command 

command ] 

• The first line instructsPSYMAKE that the file "targetfile” depends on the files 
listed as "sourcefile^' . 

• If any of the source files are dated later than the target file, or the target file does 
not exist, PSYMAKE will issue the commands that follow in order to rebuild the 
target file. 

• If no source files are specified, the target file will always be rebuilt. 

• If any of the source files do not exisd*SYMAKE will attempt to build them first 
before issuing the commands to build the current target file. PSYMAKE 
cannot find any rules defining how to build a required file, it will stop and report 
an error. 

The target file name must start in the left hand column. The commands to be 

executed in order to build the target must all be preceded by white space (either 

space or tab characters). The list of commands ends at the next line encountered with 

a character in the leftmost column. 
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Examples main.cpe: main.n64 incl.h inc2.h 

asmn64 main, main 

This tells PSYMAKE that main . cpe depends on the filesmain . n64 , incl.h 
and inc2 . h . If any of these files are dated later thamain . cpe, or main . cpe 
does not exist, the command "asmn64main, main " will be executed in order to 
create or update main . cpe. 


main.cpe: main.n64 incl.h inc2.h 
asmn64 /I main, main, main 
psylink main, main 

Here, two commands are required in order to rebuilffca in . cpe. 


Implicit Rules 

If no commands are specifiedPSYMAKE will search for an implicit rule to 
determine how to build the target file. An implicit rule is a general rule stating how to 
derive files of one type from another type; for instance, how to convealsm files into 
.exe files. 

Implicit rules take the form: 

.<source extension> .< target extension>: 
command 

[... 

command ] 

Each <extensioit> is a 1, 2 or 3 character sequence specifying the DOS file extension 
for a particular class of files. 

At least one command must be specified. 


Examples .s.bin: 

asmn64 /p $*,$* 

This states that to create a file of typebin from a file of type S, the asmn64 
command should be executed. (See below for an explanation of the $* substitutions.) 
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Executing commands 

Once the commands to execute have been determinelPSYMAKE will search for 
and invoke the command. Search order is: 

• current directory; 

• directories in the path. 


Command prefixes 

The commands in a dependency or implicit rule command list, may optionally be 

prefixed with the following qualifiers : 

@ - suppress printing of command before execution 

- number - abort if exit status exceeds specified iml 

- (without number) ignore exit status (never abort) 

• Normally, unless 4 is specified on the command lin^SYMAKE will print a 
command before executing it. If the command is prefixed by @ , it will not be 
printed. 

• If a command is prefixed with a hyphen followed by a numbP^YMAKE will 
abort if the command returns an error code greater than the specified number. 

• If a command is prefixed with hyphen without a numberPSYMAKE will not 
abort if the command returns an error code. 

• If neither a hyphen or a hyphen+number is specified, aiids^ not specified on the 
command line PSYMAKE will abort if the command returns an error code other 
than 0. 
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Macros A macro is a symbolic name which is equated to a piece of text. A reference to that 
name can then be made and will be expanded to the assigned text. Macros take the 
form: 

name = text 

• The text of the macro starts at the first non-blank character after the equals sign ( 
= ), and ends at the end of the line. 

• Case is significant in macro names. 

• Macro names may be redefined at any point. 

• If a macro definition refers to another macro, expansion takes place at time of 
usage. 

• A macro used in a rule is expanded immedia^l 

Examples FLAGS = /p /s 
. s .bin : 

asmn64 $ (FLAGS) /p $*,$* 

The %{FLAGS) in the asmn64 command will be replaced witl^y/ s. 


Pre-defined macros 

The following pre-defined macros all begin with a dollar sign and are intended to aid 
file usage: 


$d 

Defined Test Macro, e.g.: 

!if $d (MODEL) 

# if MODEL is defined 

• • • 


$* 

Base file name with path. 

e.g. 

C:\PSYQ\TEST 

$< 

full file name with path. 

e.g. 

C:\PSYQ\TEST.S 

$: 

path only. 

e.g. 

C:\PSYQ 

$. 

full file name, no path. 

e.g. 

TEST.s 

$& 

base file name, no path. 

e.g. 

TEST 


The filename pre-defined macros can only be used in command lists of dependency 
and implicit rules. 
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Directives: The following directives are available: 

!if expression 
lelseif expression 

lelse 

lendif 

These directives allow conditional processing of the text between t^ elseif, else 
and endif. Any non-zero expression \irue\ zero false. 

lerror message Print the messageand stop. 

lundet macroname Undefines a macro name. 

Expressions: Expressions are evaluated to 32 bits, and consist of the following components : 

Decimal Constants e g. 1 10 1234 
Hexadecimal e.g. $FF00 $123abc 

Monadics - ~ ! 

Dyadics + - * I %><& 

r && II 

><>=<= == (or = ) 

!= (or <> ) 

The operators have the same meanings as they do in the C language, except for = and 
<> ,which have been added for convenience. 


Value assignment 

Macro names can be assigned a calculated value; for instance: 

NUMFILES == $ (NUMFILES) +1 

( Note two equals signs in value assignment) 

This evaluates the right hand side, converts it to a decimal ascii string and assigns the 
result to the name on the left. 

In the above example, iNUMFILESwas currently "42", it will now be "43". 


Note NUMEILE = $ (NUMEILES) +1 

would have resulted irNUMFILEShecoming "42-1-1". 

Undefined macro names convert to 'O' in expressions and null string elsewhere. 


© SN Systems Ltd 





Page 14-8 


PSYMAKE Utility 


Nintendo 64 


Comments: 

Comments are introduced by a hash mark 0# 

main.exe: main.n64 # main.exe only depends 

# on main.n64 

# whole line comment 


Line continuation: 

A command too long to fit on one line may be continued on the next by making '\' the 
last character on the line, with no following spaces/tabs: 

main.exe : main.n64 11. h 12. h \ 

13 .h 14 .h 
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TBIOS2.COM 


Description: TBIOS2.COM is a DOSTSR program, which acts as a driver for the interface boai;d 
installed in the host PC 


Note: This program is only necessary if you are running DOS software. 


Syntax TBI0S2 {switched 


where each switch is preceded by a forward slas^V ) and separated by spaces. 


Switches 


/a 

card address 

Set card address: 

200 - 3f8 

/b 

buffer size 

Specify file transfer buffer size 
2 to 32 (in kilobytes) 

/d 

channel 

Specify DMA channel 
5, 6, 7; 0 = off 

/i 

intnum 

Specify IRQ number 

5, 7, 10, 11, 12, 15; O=off 

/I 

filename 

Specify Eileserver log file; All fileserver 
functions will be recorded in the specified 
file. 

/s 

id 

Override PC Interface SCSI ID jumper 
setting: 0 to 7 

/8 


Run in 8 bit slot mode 


Remarks 

• Normally, TBIOS2.COM is loaded in the AUTOEXEC.BAT! can safely be 
loaded high to free conventional memory. 

• If TBI0S2 is run again, with no options, the current image will be removed from 
memory. This is useful if you wish to change the options without rebooting the 
PC. 

• If the DMA numberis not specified, the TBI0S2 will work without DMA; 
however, it will be slower. 

• The TBI0S2 can drive the interface in 8 bitiode; however, this is the slowest 
mode of operating the interface. 

• The buffer option (/b) sets the size of the buffer used when the target 
machine accesses files on PC. A larger buffer will increase the speed of these 
accesses; however, more PC memoryvill be consumed. The default is a 1 K 
buffer. 
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Examples TBIOS2 /a308 /d7 /il5 

Start the driver using the typical settings of: 

Card address 308 

DMA channel? 

Interrupt vector 15 

Note: The downloaded bios will remain until the interface is powered off. It should 
not be necessary to switch it off during the normal course of development. It 
is possible to switch the N64 off and on or reset it without affecting the bios 
in the interface. The only thing that can cause the interface to lock up is if the 
Nintendo 64 saturates accessto the cartridge ram. If this happens switch the 
Nintendo off and allow it to recover. 

Note: If you are using Windows 95, DO NOT install TBIOS&om your 
AUTOEXEC.BAT. Only install it in one DOS)OX. 
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RUN.EXE - program downloader 

Description This program downloads runnable object code to the target machine. 

Note: TBIOS2 must be loaded in the current DOS box. 

Syntax RUN [switched file name [[switched filename..] 

where switches are preceded by a forward slash (/) 

Switches /h halt target - that is, download but do not run. 

/t# use target SCSI ID number# - always 0 for the Nintendo. 

/u# use target unit number# always 0 for the Nintendo 
/w## retry for ## seconds if target does not respond. 

Remarks If run is executed without any runtime parameters, the program will simply attempt 
to communicate with the target adapter hardware. If successful, run displays the 
target identification; if the attempt fails, an appropriate error message is displayed. 

The file to be downloaded may contain: 

• An executable image, output by the development system, in .cjkrmat. Up to 8 
cpe files may be specified 

• A raw binary image of a cartridge. 

For an executable file, execution will begin as indicated in the source code; for a 
binary ROM image, execution will begin as if the target machine had been reset with 
a cartridge in place. 

Multiple executable files may be specified. However, only the last executable address 
will apply - specified files are read from left to right. 

A binary file can be downloaded to a particular address by specifying the address 
after the file name, e.g.: 

run game.bin, bOOOOOOO 

will downloadgame . bin to address bOOOOOOO (hex). 

Note: The Windows equivalent to this program ipqrun . 
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Running with Brief 


Most programmers prefer to develop programs completely within a single, enabling 
environment. Future versions of the software will provide a self-contained 
superstructure with a built-in editor, tailored to the requirements of the assembly and 
debug sub-systems. For the time being however, these facilities can be found in 
Borland's Brief text editor. 


Installation in Brief 

In order to use Brief you will need to make a few changes to your 
AUTOEXEC. BAT file after you have installed Brief: 

Set the BCrvv environment variables These variables take the file extension of a 
source file to tell Brief how to Assemble or Compile the file. Eor example: 

set bcn64="asmn64 /i /w /d /zd %%s, tO : , %%s, , " 
set bcs="asmn64 /i /w /d /zd %%s, tO : , %%s, , " 
set bcc="ccn64 -v -g -Xo$80010000 %%s.c - 
o%%s . cpe, %%s . sym" 


These will Assemble .N64 source file with ASMN64, .S source files with the 
ASMN64 assembler (see chapter 2), and Compile .C source files with CCN64 (see 
The Build Utility chapter). 

Set the BEEAGS environment variable, with -mPSYQ appended, to force the macro 
file to be loaded on start-up. Eor example: 

set bf lags=-ai60Mk2u300p -mrestore -Dega -DlOlkey -mPSQ 

The variable may look different depending on how Brief was set up. 

Einally, copy the file PSYQ.CM, containing macros, into the \BRIEE\MACROS 
directory, or create it from source file PSYQ.CB; 


© SN Systems Ltd 






Nintendo 64 


APPENDIX A 


Page A-5 


Note: The standard Brief feature of usin^lt-FlO to compile the current file as 

instructed by the BG;cx environment variable still works as normal. However, 
if you take the time to write a simple make file for each of your projects you 
will find the System’s keystrokes much more convenient and powerful. 


The brief macros 


Ctrl-G 

Ctrl-F 

Ctrl-W 

Ctrl-V 

Ctrl-F9 

Ctrl-FlO 

Alt-F9 

F9 


Goto label (locate definition of label under the cursor in loaded source 
files) 

Return from label (undo the above operation) 

Write out all changed files 

Evaluate expression under cursor using values from symbol file(s) 

Select make file for current project 

Make program and enter debugger 

Make program and start it running 

Enter the Debugger 


If you wish to change any of these key assignments then change to your 
\BRIEE\MACROS directory and edit the file PSYQ.CB. Near the top of this file you 
will see where the keys are assigned to the various functions and it should be easy to 
change the key names and re-compile the macro by pressi^t-FlO. 


Note: If you re-assign any of the Brief standard key assignments then you may lose 
access to that original Brief function. 


Ctrl-F9 allows you to select which make file you wish to use. By default, the System 
will use the file in your current directory calldMIAKEFILE.MAK. If you do not 
wish to use this file then usdCtrl-F9 to select the preferred make file. 

Ctrl-FlO, Alt-F9 and F9 work by calling the PSYMAKE program with a suitable 
parameter to select which operation to perform. Your System disk includes a simple 
make file called MAKEEIEE.MAK as an example. If you edit this file you will see 
that it defines how to do one of three operations:- 

• Assemble and Run 

• Assemble but don't Run 

• Enter Debugger 
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It should be easy for you to adapt this file to your needs. If you are doing one simple 
assembly then all you will have to change is the name of the file that is assembled and 
add any other command line options you require. 

It does not matter which of your source files you are in when you press one of the 
make/debug keys - the make file will specify the commands to the assembler and 
debugger. 
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Assembler Messages: 

'%n' cannot be used in an expression 

%n will be the name of something like a macro or register 

'%n' is not a group 

Group name required 

' %n ' is not a section 

Section name expected but name %n was found 

Alignment cannot be guaranteed 

Warning of attempt to align that cannot be guaranteed due to the base alignment of 
the current section 

Alignment ' s parameter must be a defined name 

In call to alignment( ) function 

Assembly failed 

Text of the FAIL statement 

Bad size on opcode 

E.g. attempt to use .b when only .w is allowed 

Branch (%1 bytes) is out of range 

Branch too far 

Branch to odd address 

Warning of branch to an odd address 

Cannot POPP to a local label 

E.g. POPP @x 

Cannot purge - name was never defined 

Case choice expression cannot be evaluated 

On case statement 

Code generated before first section directive 

Code generating statements appeared before first section directive 

Could not evaluate XDEF ' d symbol 

XDEE'd symbol was equated to something that could not be evaluated 
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Could not open file ' %s ' 

Datasize has not been specified 

Must have a DATASIZE before DATA statement 

Datasize value must be in range 1 to 256 

DATASIZE statement 

Decimal number illegal in this radix 

Specified decimal digit not legal in current radix 

DEF ' s parameter must be a name 

Error in DEE( ) function reference 

Division by zero 

End of file reached without completion of %s construct 

E.g. KEPT with no ENDR 

ENDM is illegal outside a macro definition 

Error closing file 

System close file call returned an error status 

Error creating output file 

Could not open the output file 

Error creating temporary file 

Could not create specified temporary file 

Error in assembler options 

Error in expression 

Similar to syntax error 

Error in floating point number 

In IEEE32 / IEEE64 statement 


Error in register list 

Error in specification of register list for MOVEM / REG 


Error opening list file 

System open returned an error status 


Error reading file 

System read call returned an error status 
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Error writing list file 

An error occurred while writing to the list file. 

Error writing object file 

System write call returned an error or disk is full 

Error writing temporary file 

Disk write error, probably disk full 

Errors during pass 1 - pass 2 aborted 

If pass 1 has errors then pass 2 is not performed 

Expanded input line too long 

After string equate replacement, etc. line must be <= 1024 chars 

Expected comma after < > 

<...> bracketed parameter in MACRO call parameter list 

Expected comma after operand 
Expected comma between operands 

Expected comma between options 

In an OPT statement 

Expecting ' %s ' at this point 

Expecting one of ENDIF/ENDCASE etc. but found another directive 

Expecting ' + ' or ' - ' after list command 

In a EIST statement 

Expecting ' + ' or ' - ' after option 

In an OPT statement 

Expecting a number after /b option 

On Command line 

Expecting comma between operands in INSTR 
Expecting comma between operands in SUBSTR 

Expecting comma or end of line after list 

In { ... } list 

Expecting ON or OFF after directive 

In PUBEIC statement 
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Expecting options after /O 

On Command line 

Expecting quoted string as operand 

Expression must evaluate 

Must be evaluated now, not on pass 2 

Fatal error - macro exited with unterminated %s loop 

End of macro with unterminated WHILE/REPT/DO loop. 

Due to the way the assembler works, this must be treated as a fatal error 

Fatal error - stack underflow - PANIC 

Assembler internal error - should never occur! 

File name must be quoted 

Files may only be specified when producing CPE or pure binary 
output 

In EIEE attribute of group 

Forward reference to redefinable symbol 

Warning that a forward reference was made to a symbol that was given a number of 
values in SET or = statements. The value used in the forward reference was the last 
value the symbol was set to. 

Function only available when using sections 

Group ' %n ' is too large (%1 bytes) 

Group exceeds value in SIZE attribute 

GROUP ' s parameter must be a defined name 

In GROUP( ) function call 

GROUPEND ' s parameter must be a group name 

Error in call to GROUPEND( ) function 

GROUPORG ' s parameter must be a group 

In call to GROUPORG( ) function 

GROUPSIZE ' s parameter must be a group name 

Error in call to GROUPSIZE( ) function 

IF does not have matching ENDIF/ENDC 

Illegal addressing mode 

Addressing mode not allowed for current op code 


© SN Systems Ltd 


Nintendo 64 


APPENDIX B - Error Messages 


Page B-5 


Illegal character ' %c ' (%d) in input 

Strange (e.g. control) character in input file 

Illegal character ' %c ' in opcode field 

Illegal digit in suffixed binary number 

In alternate number form 101b 

Illegal digit in suffixed decimal number 

In alternate number form 123d 

Illegal digit in suffixed hexadecimal number 

In alternate number form labh 

Illegal group name 

Illegal index value in SUBSTR 

Illegal label 

Label in left hand column starts with illegal character 

Illegal name for macro parameter 

In macro definition 

Illegal name in command 

Target name in ALIAS statement 

Illegal name in locals list 

In LOCAL statement 

Illegal name in XDEF/XREF list 

Illegal parameter number 

Maximum of 32 parameters 

Illegal section name 

Illegal size specifier for absolute address 

Can only use .w and .1 on absolute addressing 

Illegal start posit ion/length in INCBIN 

Illegal use of register equate 

E.g. using a register equate in an expression 

Illegal value (%1) 

Illegal value (%1) for boundary in CNOP 
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Illegal value (%1) for offset in CNOP 
Illegal value for base in INSTR 

Initialised data in BSS section 

BSS sections must be uninitialised 

Instruction moved to even address 

Warning that a padding byte was inserted 

Label ' %n ' multiply defined 

LOCAL can only be used inside a macro 

LOCAL statement found outside macro 

Local labels may not be strings 

@x EQUS ... is illegal 

Local symbols cannot be XDEF ' d/XREF ' d 
MEXIT illegal outside of macros 
Missing ' ( ' in function call 
Missing ') ' after function parameter (s) 

Missing ' ) ' after file name 

In FILE attribute 

Missing closing bracket in expression 

Missing comma in list of case options 

In =... case selector 

Missing comma in XDEF/XREF list 
MODULE has no corresponding MODEND 

Module may not end until macro/loop expansion is complete 

If a loop / macro call starts inside a module then there must not be a MODEND until 
the loop / macro call finishes 

Module must end before end of macro/loop expansion - MODEND 
inserted 

A module started inside a loop / macro call must end before the loop / macro call 
does 

More than one label specified 

Only one label per line (can occur when second label does not start in left column but 
ends in ) 
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Move workspace command can only be used when downloading 

In WORKSPACE statement 

Names declared with local must not start with ' %c ' 

In LOCAL statement 

NARG can only be used inside a macro 

Use of NARG outside macro 

NARG ' s parameter must be a number or a macro parameter name 

Illegal operand for NARG( ) function 

No closing quote on string 

No corresponding IF 

ENDIL/ELSE without IE 

No corresponding DO 

UNTIL without DO 

No corresponding REPT 

ENDR without REPT 

No corresponding WHILE 

ENDW without WHILE 

No matching CASE statement for ENDCASE 

ENDCASE without CASE 

No source file specified 

No source file on command line 

Non-binary character following % 

Non-hexadecimal character ' %c ' encountered 

In HEX statement 

Non-hexadecimal character starting number 

Expecting 0-9 or A-E after $ 

Non-numeric value in DATA statement 

OBJ cannot be specified when producing linkable output 

OBJ attribute on group 

Odd number of nibbles specified 

In HEX statement 

OFFSET ' s parameter must be a defined name 

Error in OEESET( ) function call 
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Old version of %n cannot be purged 

Only macros can be purged 

One string equate can only be equated to another 

Attempt to equate to expression, etc. 

Only one of /p and /I may be specified 

On Command line 

Only one ORG may be specified before SECTION directive 
Op-code not recognised 

Option stack is empty 

POPO without PUSHO 

Options /I and /p not available when downloading to target 

On Command line 

ORG ? can only be used when downloading output 

ORG address cannot be specified when producing linkable 
output 

No ORG group attributes when producing linkable output 

ORG cannot be used after SECTION directive 

ORG cannot be used when producing linkable output 

ORG must be specified before first section directive 

When using sections only one ORG statement may appear before all section 
statements (other than as group attributes) 

Out of memory. Assembler aborting 

Out of stack space, possibly due to recursive equates 

Assemblers stack is full, possible cause is recursive equates, e.g. x equ y+1 , y equ 
x*2 
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Overflow in DATA value 

DATA value too big 

Overlay cannot be specified when producing linkable output 

No OVER group attributes when producing linkable output 

Overlay must specify a previously defined group name 

Error in OVER group attribute 

Parameter stack is empty 

POPP encountered but nothing to pop 

POPP must specify a string or undefined name 

Possible infinite loop in string substitution 

E.g. reference to x where x is defined as x equs x+1 

Previous group was not OBJ'd 

OBJ( ) attribute specified but previous group had no obj attribute to follow on from 

Psy-Q needs DOD version 3.1 or later. 

Purge must specify a macro name 
Radix must be in range 2 to 16 

REF ' s parameter must be a name 

Error in REE( ) function reference 

Register not recognised 

Expecting a register name but did not recognise 

Remainder by zero 

As for division by 0 but for % (remainder) 

Repeat count must not be negative 

REPT statement error 


Replicated text too big 

Text being replicated in a loop must be buffered in memory but this loop was too big 
to fit 

Resident SCSI drivers not present . 


SCSI card not present - assembly aborted 

sect's parameter must be a defined name 
Error in SECT( ) function call 
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SECTEND ' s parameter must be a section name 

Error in call to SECTEND( ) function 

Section stack is empty 

POPS without PUSHS 

Section was previously in a different group 

Section assigned to a different group on second invocation 

SECTSIZE's parameter must be a section name 

Error in call to SECTSIZE( ) function 

Seek in output file failed 

DOS seek call returned error status 

Severity value must be in range 0 to 3 

In INEORM statement 

SHIFT can only be used inside a macro 

SHIET statement outside macro 

Short macro calls in loops/macros must be defined before 
loop/macro 

Short macros may not contain labels 

Size cannot be specified when producing linkable output 

SIZE attribute on group 

Size specified in /b option must be in range 2 to 64 

On command line 

Square root of negative number 

Statement must have a label 

No label on, for example, EQU op 

STRCMP requires constant strings as parameters 
String '%n' cannot be shifted 

String specified in SHIET statement is not a multi-element string (i.e. {...} bracketed) 
and so cannot be shifted. 

STRLEN's operand must be a quoted string 
Symbol '%n' cannot be XDEF ' d/XREF ' d 
Symbol '%n' is already XDEF ' d/XREF ' d 
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Symbol '%n' not defined in this module 

Undefined name encountered 

Syntax error in expression 

Timed out sending data to target 

Target did not respond 

Too many characters in character constant 

Character constants can be from 1 to 4 characters 

Too many different sections 

There is a maximum of 256 sections 

Too many file names specified 

On command line 

Too many INCLUDE files 

Limit of 5 12 INCLUDE files 

Too many INCLUDE paths specified 

Too many INCLUDE paths in /j options on command line 

Too many output files specified 

Maximum of 256 output files 

Too many parameters in macro call 

Maximum number of parameters (32) exceeded 

Too much temporary data 

Assembler limit of 16m bytes of temporary data reached 

TYPE ' s parameter must be a name 

Call of TYPE( ) function 

Unable to open command file 

Erom Command line 

Undefined name in command 

Target name in AEIAS statement 

Unexpected case option outside CASE statement 

Eound =... statement outside CASE/ENDCASE block 

Unexpected characters at end of Command line 
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Unexpected characters at end of line 

End of line expected but there were more characters encountered (other than 
comments) 

Unexpected end of line 

Unexpected end of line in macro parameter 

Unexpected end of line in list parameter 

In { ... } list 

Unexpected MODEND encountered 

MODEND without preceding MODUEE 

UNIT can only be specified once 

In UNIT statement 

UNIT cannot be used when producing linkable output 

In UNIT statement 

Unknown option 

In OPT statement 

Unknown option /%c 

Unknown option on Command line 

Unrecognised attribute in GROUP directive 

Unrecognised optimisation switch ' %c ' 

In OPT statement or Command line 

User pressed Break/Ctrl-C 

Assembly aborted by user 

XDEF ' d symbol %n not defined 

Symbol was XDEE'd but never defined 

XDEF/XREF can only be used when producing linkable output 
Zero length INCBIN - Warning of zero length INCBIN statement 
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Psylink Error Messages 


Linker Messages: 

%t %n redefined as section 

New definition of previously defined symbol 

%t '%n' redefined as group 

New definition of previously defined symbol 

%t '%n' redefined as XDEF symbol 

New definition of previously defined symbol 

Attempt to switch section to %t '%n' 

Non-section type symbol referenced in section switch 

Attempt to use %t ' %n ' as a section in expression 

Section type symbol required 

Code in BSS section ' %n ' 

BSS type sections should not contain initialised data 

COFF file has incorrect format 

COFF format files are those produced by Sierra C cross compiler, etc. 

Different processor type specified 

Object code is for different processor type than target or attempt was made to link 
code for different processor types 

Division by zero 

Error closing file 

Close file call returned error status 

Error in /e option 

On Command line 

Error in /o option 

On Command line 
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Error in /x option 

On Command line 

Error in command file 

Error in Linker options 

On Command line 

Error in REGS expression 

Error reading file %f 

Read file call returned error status 

Error writing object file 

Write file call returned error status - probably disk full 

Errors during pass 1 - pass 2 aborted 

Pass 2 does not take place if there were errors on Pass 1 

Expecting a decimal or hex number 

/o option on Command line 

File %f is in out-of-date format 

File should be re-built before re-assembling 

File %f is not a valid library file 
File %f is not in PsyLink file format 

Group ' %n ' is too large (%1 bytes) 

Group is larger than its size attribute allows 

Group '%n' specified with different attributes 

Different definitions of a group specify different attributes 

Illegal XREF reference to %t ' %n ' 

Object file defines xref to symbol which cannot be xrefd, e.g. a Section name 

Multiple run addresses specified 

More than one run address specified 

No source files specified 

No source file on Command line 
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Object file made with out-of-date assembler 

File should be re-built before re-assembling 

Only built in groups can be used when making relocatable 
output 

When /r command line option is used, only the built in groups can be used, i.e. no 
new groups may be defined 

Option /p not available when downloading to target 

Options /p and /r cannot be used together 

On Command line 

ORG ? can only be used when downloading output 
Out of memory. Linker aborting 

Previous group was not OBJ'd 

Cannot specify OB J() attribute if previous group did not have obj attribute 

Reference to %t '%n' in expression 

Use of, e.g. a section name in an expression 

Reference to undefined symbol #%h 

There is an internal error in the object file 

Relocatable output cannot be ORG ' d 
Remainder by zero 

Run-time patch to odd address 

Warning that a run-time longword patch to an odd address will occur which may 
cause some Amiga systems to crash 

SCSI Card not present - Linking aborted 

Could not find SCSI Card 

SCSI drivers not loaded 

Section '%n' must be in one of groups code, data or BSS 

When producing Amiga format code 
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Section '%n' placed in non-group symbol #%h 

There is an internal error in the object file 

Section ' %n ' placed in non-group symbol ' %n ' 

An attempt was made to place a section in a non-group type symbol 

Section '%n' placed in two different groups 

Section is placed in different groups 

Section '%n' placed in unknown group symbol #%h 

There is an internal error in the object file 

Section '%n' must be in one of groups text, data or BSS 

When producing ST format code 

Symbol '%n' multiply defined 

New definition of previously defined symbol 

Symbol '%n' not defined 

Undefined symbol 

Symbol '%n' placed in non-section symbol #%h 

There is an internal error in the object file 

Symbol '%n' placed in unknown section symbol #%h 

There is an internal error in the object file 

Symbol in COFF format file has unrecognised class 

COFF format files are those produced by Sierra C cross compiler, etc. 

Timed out sending data to target 

Target not responding or offline 

Too many file names specified 

Too many parameters on command line 

Too many modules to link 

Maximum of 256 modules may be linked 

Too many symbols in COFF format file 

COFF format files are those produced by Sierra C cross compiler, etc. 

Unable to open output file 

Could not open specified output file 

Undefined symbol in COFF file patch record 

COFF format files are those produced by Sierra C cross compiler, etc. 

Unit number must be in range 0-127 
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Unknown option /%c 

On Command line 

Unknown processor type '%s' 

Could not recognise target processor type 

Unrecognised relocatable output format 

/r option on command line 

User pressed Break/Ctrl-C 

Linking aborted by user 

Value (%1) out of range in instruction patch 

Value to be patched in is out of range 

WORKSPACE command can only be used when downloading output 
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Psylib Error Messages 


Librarian Messages: 

Cannot add module : it already exists 

Module may only appear in a library once 

Could not create object file 

Error creating object file when extracting 

Could not create temporary file 

Error creating temporary file 

Could not open/ create 

System error opening file 

Error reading library file 

System error occurred reading file 

Error writing library file 

System error writing file, probably disk full 


Incorrect format in object file 

Error in object file format - re-build it 


No files matching 

No object files matching the specifications were found 


No library file specified 
No object files specified 
No option specified 

An action option must be specified on the command line 

Unknown option / 

On Command line, option not recognised 
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